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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those: it routes to one of many tools, fills arguments, returns structured answers with stable citation URIs, and works on every tier with one fast call. It does not mention rate limits or error behavior, but for a read-only, idempotent tool the safety profile is already covered.

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 the most critical decision rule ('PREFER OVER WEB SEARCH') and the data domains. Examples and alternative-tool guidance earn their place for a complex routing tool. Minor redundancy exists between 'even if web search could also answer it' and the opening preference statement, but overall the structure is effective and scannable.

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 absence of an output schema, the description adequately explains the return type (structured answer with pipeworx:// citation URIs), the scope (5,724 tools / 1497 sources), the invocation patterns, and the escalation path to siblings. An agent receives enough context to call this tool appropriately without further inference.

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

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

Schema description coverage is 100%, so the schema fully documents the six parameter aliases and the required 'question' field. The description does not add parameter-level detail, which is acceptable because the schema is self-sufficient. This meets the baseline but provides no extra semantic value beyond what the schema already includes.

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

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

The description clearly identifies the tool as the default entry point for factual questions over authoritative structured data, listing concrete categories (SEC filings, FDA, FRED/BLS, USPTO, etc.) and the routing function across 5,724 tools. It also explicitly distinguishes itself from ask_pipeworx_grounded and deep_research. This goes beyond the mere title and gives an agent a precise operational picture.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It also tells the agent when to step up to alternatives (grounded for verbatim evidence, deep_research for broad multi-part questions) and even addresses news-breaking coverage. No ambiguity remains about selection.

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 covering read-only and non-destructive behavior, the description adds valuable behavioral detail: candidate routing improvements are only active when under test, none is active currently, and it is a fully working router with no fallback. This clarifies that 'beta' means experimental parity, not a broken or partial tool.

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 tool's identity and purpose, and every sentence earns its place. There is minor redundancy between 'currently matches ask_pipeworx exactly' and 'Use it exactly like ask_pipeworx,' but it is not wasteful.

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

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

The description covers how to invoke it, its current experimental state, parity with ask_pipeworx, and the absence of a fallback. There is no output schema, but referencing 'same response shape' as a known sibling is acceptable context for an agent selecting and calling the tool.

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

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

The input schema provides 100% coverage, documenting the required question parameter and all five aliases with descriptions. The tool description adds no new parameter-level meaning beyond saying 'same arguments' as ask_pipeworx, which is enough given full schema coverage.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, a universal router with 5,724 tools and identical arguments/response shape. It distinguishes itself from the stable sibling by emphasizing its experimental routing edge, leaving no ambiguity about what the tool is.

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 says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly state 'do not use for production' but the beta/experimental framing implies the boundary.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the exact success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the full refusal contract with all five refusal_reason values. It also reveals the extra LLM call cost and that it uses the same routing as ask_pipeworx but then grounds the answer only in fetched results. This is rich, non-redundant behavioral disclosure.

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: definition, behavior, return contract, refusal contract, use cases, and cost tradeoff. It is front-loaded with the core differentiator and avoids filler or repetition of schema fields. The structural flow moves from identity to mechanics to usage guidance 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?

Even without an output schema, the description fully specifies successful return fields, evidence behavior, refusal reasons and conditions, and the sibling tradeoff. It also provides enough operational context (routing, grounding, cost) for an agent to decide when to invoke this tool over ask_pipeworx. There are no critical gaps 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%, with the question parameter and all five aliases clearly documented. The description adds that the input is a natural-language question and that the tool internally fills arguments and fetches data, but it does not elaborate on parameter semantics beyond the schema. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a precise verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes this from the sibling ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains' and by explicitly naming ask_pipeworx as the alternative. The scope, behavior, and refusal semantics are all specified in concrete terms.

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

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

The description gives explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on' for high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups' because this mode costs one extra LLM call. This directly routes an agent between the two siblings without ambiguity.

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

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

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?

Annotations already mark the operation read-only, idempotent, and non-destructive; the description adds substantial beyond-annotation context: account requirements, paid plan for thorough depth, expected latency, parallel tool routing, gaps[] behavior, contradictions[], hop fields, semantic excerpting, and fetchable citation guarantees. There is no contradiction with the annotations.

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

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

The description is long but information-dense and front-loads the most decision-critical facts: account requirement, fallback tool, and the crucial 'not open-web search' clarification. Structure is a single large block rather than scannable sections, but nearly every sentence earns its place given the tool's complexity.

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

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

Even without an output schema, the description covers the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop), expected latency, access prerequisites, and routing to siblings. An agent has everything needed to decide when to call this tool and what to expect back.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: what each depth level actually does at runtime (gap recovery, lead chasing, contradiction scan), the paid restriction on thorough, and the intended shape of the question parameter. This lifts it above baseline without needing to compensate for schema gaps.

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 names a specific verb and resource: it decomposes questions into facets and runs parallel research across Pipeworx's 1,497 structured data sources, returning a findings packet. It explicitly contrasts itself with open-web search and with ask_pipeworx, making sibling differentiation unambiguous.

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

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

It gives explicit when-to-use guidance (broad/multi-part structured-data questions), when-not-to-use guidance (single lookups, breaking/current-news topics), and names the alternative tool to route to (ask_pipeworx). It even covers the unsigned-in fallback case, leaving no usage decision to inference.

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?

The description goes far beyond the readOnly/idempotent annotations: it explains compatibility_warning and compatibility_codes[] semantics, per-pair flags, skipped_unclassified handling, the gross-vs-net spread limitation via fees_note, null temporal_alignment meaning, and the standing pairing_unverified disclosure. There is no contradiction with the annotations.

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

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

The description is long but appropriately structured: definition, modes, response format, safety fields, codes, counters, and final caveat. It is front-loaded with the core concept. Minor redundancy exists, such as repeating that both modes share the same disclosures, but for a tool this behaviorally rich the length is largely earned.

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

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

With no output schema, the description carries the full burden of explaining the return contract, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, safety fields, compatibility codes, skipped counters, temporal_alignment semantics, and the fees note. Edge cases like null alignment, unclassified legs, and low-confidence pairs are all covered, so an agent has enough context to call and interpret the tool.

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

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

The schema already covers 100% of the parameters, so the baseline is 3. The description adds meaningful semantics by explaining that explicit parameters override the topic-mapped side, that `topic` is a pre-mapped shortcut list, and that both modes run the identical token-overlap matcher. This is useful enrichment, though not a substitute for missing schema coverage.

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

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

The description opens with a precise verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also names two concrete modes and the response content, making the tool's role distinct from related siblings like polymarket_edges or polymarket_arbitrage even without explicitly naming them.

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

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

The description gives clear mode-selection guidance: use `topic` for 10 pre-mapped shortcuts and explicit ticker/slug for custom pairings, and it explicitly warns that both modes share the same matching logic and that 'pre-mapped ≠ tradeable.' It stops short of contrasting this tool with sibling alternatives, so it falls just below the explicit when-not-to-use benchmark.

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 cover read-only, idempotent, open-world behavior, so the description earns credit by adding substantial process detail: internal cascades through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, source-labelled identifiers, and `figi_candidates` on ambiguous matches. This goes well beyond the annotation hints.

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

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

The description is dense and somewhat run-on, but every major sentence adds operational value and the most important routing guidance ("Use FIRST") is front-loaded. Some restructuring into clearer bullets would improve scannability, but the content justifies the length for a tool with this complexity.

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

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

For a two-parameter, no-output-schema tool, this description is unusually complete: it covers supported types, input formats, disambiguation output, unresolved identifiers, source labelling, enrichment failure behavior, and internal cost. An agent has enough to call and interpret results correctly in most cases.

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

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

Even though schema coverage is 100%, the description adds meaning beyond the schema: it documents ISIN as an accepted input, explains how ISIN maps to legal entities, clarifies entity-name-only for bonds, warns that trailing security-class words fail FIGI matching, and explains ambiguity behavior. This materially improves an agent's chance of passing the right value.

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

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

The description states a precise purpose: resolving user-spoken names into canonical/official identifiers required by other tools, with concrete call-pattern examples for ticker, CIK, LEI, RxCUI, and FIGI. It clearly distinguishes itself from broader siblings by framing itself as the identifier-lookup step and listing supported entity types.

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

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

It gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID." It does not name alternative sibling tools or exclusions, but the instruction is direct and the supported-type breakdown makes the intended call situation 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 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description provides rich behavioral context: it details two distinct processing pipelines (SEC EDGAR fast path vs. grounded pipeline), enumerates the possible verdicts, and carefully distinguishes 'could_not_verify' from 'unsupported' with explicit instructions on how to handle each. It also notes the tool replaces 4-6 sequential calls, giving the agent a clear operational model.

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

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

The description is concise yet dense, front-loaded with trigger phrases and followed by structured operational details: usage, processing paths, return values, and caveats. Every sentence serves a purpose, and the formatting (inline lists) keeps it scannable without wasting words.

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

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

The description is fully self-contained: it explains what inputs are needed, how the tool behaves under different claim types, what output shape to expect (verdicts, actual value, citation, reasoning), and how to interpret edge cases (could_not_verify, unsupported). This is especially complete given no output schema is provided, preparing the caller for all likely outcomes.

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

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

The schema already provides comprehensive descriptions for both parameters (claim and tolerance_pct) with examples and constraints. The description adds context about claim semantics ('natural-language factual claim') and mentions the percent-delta math, but the schema covers the essential meaning. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a natural-language claim verification tool, providing specific trigger phrases ('fact check', 'verify the claim that…', 'true or false') and a direct statement: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between two processing paths, making the function unambiguous and distinct from sibling tools like search or research.

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

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

The description gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the automatic routing for both company-financial claims and any other factual claims. While it doesn't explicitly mention sibling tools as alternatives, the clear trigger phrases and universal scope leave little ambiguity about when to invoke this tool.

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