Json

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds specifics: default model is free Workers AI Llama-3.3-70b, Anthropic probing requires BYO API key with direct billing, and return format per-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?

Two sentences: first covers core functionality and default, second covers optional key and return structure. Front-loaded, no wasted words.

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

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

For a 4-param read-only tool with no output schema, description explains return structure (per-model objects with score, confidence, signals, raw_response + combined view) and cost behavior. Complete for agent use.

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

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

Schema coverage is 100% (all 4 params described). Description adds value beyond schema by clarifying cost implications for _apiKey and disambiguation purpose for context.

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

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

Description clearly states the tool probes LLMs for brand visibility and scores it (0-100). It distinguishes from siblings like ask_pipeworx which focus on specific queries about Pipeworx.

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

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

Description provides use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default vs. paid model usage but doesn't explicitly contrast with sibling tools or state when not to use.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses routing behavior across 5,706 tools, argument filling, structured answers, stable pipeworx:// citation URIs, one-call speed, and tier availability. 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?

Although long, the description is front-loaded with the priority directive, organized with examples and explicit step-up alternatives. Every section earns its place for a tool that is a default entry point with many sibling tools.

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?

It covers purpose, trigger phrases, examples, alternatives, return behavior (structured answer with citation URIs), operational traits (one fast call, works on every tier), and breaking-news handling. No output schema exists, but the description adequately states what the caller gets 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% and documents the question parameter plus five aliases, so the schema already carries the semantic load. The description contributes example queries and trigger phrases but adds no parameter format or constraint details beyond the schema.

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

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

The description names a specific action ('routes the question to the right one of 5,706 tools... returns the structured answer') and a clear resource domain (SEC, FDA, FRED, USPTO, ATTOM, weather, etc.). It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

It explicitly tells agents to prefer this over web search for factual/data questions, lists trigger phrases, and gives when-not-to-use guidance by naming ask_pipeworx_grounded for grounded single answers and deep_research for broad multi-part questions. Includes concrete examples for when to invoke.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description discloses the experimental nature: routing improvements may be 'enabled live whenever one is under test,' and current behavior matches the stable router. It also reveals that usage feeds into evaluation ('results are compared against the stable router'), which an agent would not otherwise know.

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

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

Four sentences, all relevant, and the key identity ('Beta version of ask_pipeworx') is front-loaded. It is slightly verbose with the retirement date and repeated emphasis, but every sentence contributes to correct use or expectation-setting.

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

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

For a router with no output schema, the description gives critical context: it is a fully functional router, currently identical to the stable version, and its responses have the same shape as ask_pipeworx. It does not detail the response structure, but since ask_pipeworx is a sibling tool, the agent can infer it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter meaning beyond saying 'same arguments' as ask_pipeworx, but the input schema already fully documents the question field and its aliases.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, explicitly calling it an 'identical universal router' with 'same 5,706 tools, same arguments, same response shape.' It also distinguishes itself from the stable ask_pipeworx by noting it is the experimental edge, so an agent can separate it from siblings like ask_pipeworx_grounded.

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

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

The description gives an explicit condition for use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies what the tool is not (it 'falls back to nothing') and states that results are compared against the stable router, preventing misuse as a placeholder.

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 say readOnly/idempotent, and the description adds non-obvious behavior: output always returns evidence as verbatim quote, explicit refusal reasons with five enumerated values, and a guarantee that it extracts only from the tool result. It also discloses an extra LLM call cost, which annotations cannot express.

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

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

Every sentence serves a purpose: definition, routing, extraction guarantee, success/refusal shapes, use cases, and cost tradeoff. The most decision-relevant info (hallucination resistance, when to use, sibling) 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 complex tool with no output schema, it fully specifies the return contract (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerates all refusal reasons. It also connects to its sibling and explains cost/risk, so an agent can decide and call it without missing information.

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 every parameter is an alias for the same natural-language 'question' field, all documented in the schema. The description adds no parameter-level detail beyond saying it 'fills arguments' internally, so baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads'—a specific verb (answer/extract) and resource (Pipeworx knowledge). It explicitly contrasts with sibling ask_pipeworx by saying 'Same routing as ask_pipeworx' but with stricter extraction using only tool results, so an agent can tell them apart.

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

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

Explicit use cases are given: whenever the answer will be quoted, cited, or acted on, and facts must not be invented. It also gives a cost tradeoff ('Costs one extra LLM call vs ask_pipeworx') and an exclusion: 'prefer ask_pipeworx for casual lookups'.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral details: resolver contract, parent event extractor, news fields, safety behaviors (low-confidence short-circuit, closed market handling), and response shapes. 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?

Description is long but well-organized with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). Every sentence adds essential information for a complex tool. Slight wordiness but justified by depth of behavior.

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

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

Despite no output schema, description thoroughly documents response shapes, all fields (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads, resolution rules), and blocking paths. Complete for agent understanding.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds significant value beyond schema by explaining market flexibility, depth options (quick/thorough), include_raw for raw payloads, and default behaviors.

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

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

Description clearly states it researches Polymarket bets by pulling Pipeworx data, lists input types (slug, URL, question text), and outputs evidence packet with comparison. It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on 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?

Explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides extensive guidance on classifiers, fan-out examples, and critical caveats about low-confidence matches, closed markets, resolution-rule risk, and tradeability.

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. The description adds behavioral context: it handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. It does not contradict annotations and provides useful operational details beyond the structured fields.

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

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

The description is front-loaded with example queries and key preference guidance. Every sentence adds value: usage patterns, data sources, sorting, output format. While somewhat long, the complexity of the tool (two entity types, multiple metrics) justifies the length. Minor redundancy with schema constraints could be trimmed.

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

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

Despite no output schema, the description thoroughly explains what each entity type returns: for companies, specific financial metrics from SEC EDGAR; for drugs, FAERS adverse-event counts, approval counts, trial counts. It mentions sorting, citation URIs, and off-calendar handling. For a comparison tool replacing many lookups, this is complete and actionable.

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 enriches parameter meaning by explaining that 'type' determines the data source (company vs drug) and giving concrete examples for 'values' (tickers/CIKs for company, drug names for drug). It also reiterates the 2–5 range and adds sorting behavior, providing more context than the schema alone.

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

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

The description opens with concrete usage examples like 'Compare X and Y' and 'X vs Y', clearly stating it performs side-by-side comparison of 2–5 entities. It distinguishes between 'company' (financial data from SEC EDGAR) and 'drug' (FAERS data), and explicitly prefers this tool over sequential lookups, differentiating it from sibling tools like 'entity_profile'.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. It also implies alternatives by naming the sequential approach, and describes data sources and constraints, helping the agent decide 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral details: it requires an account, thorough depth is paid, it is not open-web search, it returns a packet with gaps[] and contradictions[], findings carry hop fields and resolvable citations, records are semantically excerpted, and latency is 15-90s. These traits are not derivable from the schema or annotations and are critical for callers to set expectations.

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

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

The description is long but densely packed with necessary information, and it is front-loaded with the account requirement and core capability. Every major section (what, when, alternatives, depth semantics, citations, latency) earns its place, though the wall-of-text format with run-on sentences slightly reduces scannability and could be improved with tighter paragraph breaks.

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

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

For a complex tool with only two parameters, no output schema, and rich annotations, the description covers all operational essentials: prerequisites, expected latency, output packet structure, citation behavior, gap handling, and exclusions. An agent can decide, call, and interpret results without consulting external 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?

Even though the schema covers both parameters, the description enriches depth semantics by explaining the facet counts, hop behavior, and contradiction scans for quick/standard/thorough — details the enum descriptions only summarize. It clarifies the practical implications of each depth choice, something an agent would not infer from the raw enum strings alone.

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 definition: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources... in ONE call' and explains the decomposition and parallel routing to 5,706 tools. It explicitly contrasts itself with open-web search and names the sibling it is not, ask_pipeworx, making the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and provides clear alternatives with conditions: 'For a single lookup use ask_pipeworx' and for breaking/current-news topics 'prefer ask_pipeworx'. It also states the account prerequisite and fallback when not signed in, leaving no ambiguity about when this tool should be selected.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that the tool returns top-N relevant tools with full schemas and curated examples, ready to call immediately. This goes beyond annotations and is accurate.

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 domain examples and then return behavior. It is slightly verbose but every sentence adds value. No redundancy.

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

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

The tool has 6 parameters (100% schema coverage) and no output schema. The description fully explains the return format: top-N relevant tools with names, descriptions, and full input schemas. Given the absence of output schema, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions aliases but does not add significant meaning beyond what the schema already provides. The examples in the schema input field are good but not part of the description text.

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 starts with 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-tool for discovering other tools.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also details use cases like browse, search, look up, discover. While it does not mention when not to use, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about patent soft-fail and data source details. 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 detailed and front-loaded with example queries. While slightly verbose, it efficiently communicates the tool's capabilities and structure.

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?

No output schema, but the description enumerates return fields (CIK, filings, fundamentals, patents, news, LEI). Could mention pagination or limits on filings, but overall complete for its complexity.

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

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

Schema coverage is 100%, and the description adds meaning by explaining that 'value' accepts ticker or CIK but not names, and that 'type' is currently limited to 'company'. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources and return fields, and distinguishes it from sibling tools like resolve_entity.

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: 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also states when not to use it (if only have a name, use resolve_entity first).

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

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

Annotations already provide destructiveHint and idempotentHint. The description adds usage context but not deeper behavioral traits (e.g., whether deletion is permanent or requires confirmation).

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 with no wasted words; first sentence delivers the core action, second provides usage context.

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 deletion tool with one parameter and no output schema, the description is nearly complete; could mention return value but not essential.

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 a clear description for 'key'. The description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from sibling tools like 'remember' and 'recall' by its destructive action.

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

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

Explicitly tells when to use (context stale, task done, clear sensitive data) and pairs with 'remember' and 'recall', but does not explicitly state when not to use alternatives.

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

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

The description adds context beyond annotations by stating it is 'Keyless, offline' and explaining the behavior of the indent parameter. No contradictions with annotations.

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

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

Two sentences with no wasted words. The main purpose is front-loaded, and the parameter behavior is efficiently described.

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?

All essential information is provided: purpose, parameter behavior, and safety traits via annotations. No output schema needed. Sufficient for an agent to invoke correctly.

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

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

The schema already covers both parameters (100% coverage), but the description adds value by specifying default indent of 2 and that 0 means minify, clarifying the parameter's behavior.

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 'Pretty-print or minify a JSON string,' providing a specific verb and resource that distinguishes it from sibling tools like validate_json or query_json.

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 mentions 'Keyless, offline,' clarifying that no external dependencies are needed, but does not explicitly guide when to use this tool versus alternatives like query_json.

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

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

Description discloses fetching, extraction, and output format (standard llms.txt markdown), adding value beyond annotations which already include readOnlyHint, idempotentHint, etc. No contradiction.

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

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

Four sentences with no wasted words, front-loaded with core purpose, followed by behavioral details and use cases.

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 2 params and clear annotations, the description adequately covers behavior and output. Could mention error handling or size limits but not required.

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

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

Schema coverage is 100% for 2 params, so baseline 3 applies. The description does not add parameter details but implies URL is primary and max_links is optional, which is sufficient.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file for any URL', clearly distinguishes from siblings like scan_competitor_ai_presence by specifying the output format and target use cases.

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

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

Provides explicit use cases (client indexing, own project, competitor audit) but lacks guidance on when not to use this tool or alternatives beyond implied differentiation.

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, destructiveHint. The description adds that it lists only the caller's subscriptions and restricts to active ones by default, providing scope beyond annotations. No contradictions.

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

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

The description is two sentences, front-loaded with the purpose, followed by return fields and usage guidance. Every sentence adds value with no redundancy.

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

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

Given the low complexity (one optional param, no output schema), the description fully covers purpose, return fields, and usage context. No gaps are evident.

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 full coverage (100%) with a description for the single optional parameter. The tool description does not add further parameter details, 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 'List the caller's active subscriptions' and specifies the returned fields (id, type, params, etc.), making the action and resource unambiguous. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This offers good guidance but doesn't explicitly mention when not to use it or alternative tools.

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

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

With all annotations set to false/absent, the description carries the behavioral disclosure burden. It discloses rate limiting (5/day), claim_token mechanics, that it's free, and the daily digest processing. It doesn't mention side effects like persistence, but the token mechanism implies it; still strong 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 a single dense paragraph with no filler. Every sentence adds value, from purpose to exclusions to behavioral details. Length is justified by the multi-faceted nature of the tool, and it is appropriately front-loaded with the core purpose.

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

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

Given the four parameters, nested context object, and lack of output schema, the description covers all necessary ground: what the tool does, when to use, how to format feedback, claim_token flow, rate limit, and routing. No output schema exists, so the description's explanation of claim_token return value fills that gap.

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

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

Schema covers all 4 params with descriptions (100%), so baseline is 3. The description adds extra guidance beyond schema, such as explaining claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to describe issues in terms of Pipeworx tools rather than pasting user prompts, which enriches 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a clear verb+resource statement. It further distinguishes itself from siblings by specifying categories (bug, feature, data_gap, praise) and routing constraints.

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

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

It explicitly states when to use ('Use when a tool returns wrong/stale data...') and when not to ('if the tool came from a different MCP server... file it with that server instead'), naming alternatives. It also provides a disambiguation rule for identifying Pipeworx tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds value beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' No contradiction.

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

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

Three substantial sentences with bullet-point-like list for use cases. No wasted words, though slightly verbose. Information is front-loaded with the core purpose.

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

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

For a simple tool with one optional parameter and no output schema, description covers purpose, usage, and behavior. Lacks detail on return format (e.g., structure of results), but the mention of 'top tools, top packs, and total call volume' provides sufficient context.

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

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

Schema coverage is 100% with one enum parameter. Description enriches semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Provides practical guidance beyond the enum values.

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

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

Description uses specific verb 'Returns' and lists resources (top tools, top packs, total call volume) with time windows. Clearly distinguishes from siblings like ask_pipeworx by being a discovery/trending tool.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking use case alignment). Provides clear context for when to use, though doesn't explicitly state when not to use or mention alternatives.

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

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

Beyond annotations (readOnly, idempotent), the description discloses scanning scope (top ~200 markets), threshold for signals (deviations >3pp), filtering mechanisms (semantic anchor Jaccard ≥0.30, placeholder fraction >20%), and response structure including fill check behavior. All behavioral traits are clearly explained without contradiction.

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

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

The description is well-structured with clear sections for each mode and technical details like fill checks, but it is slightly verbose (~250 words). Every sentence adds value, but some technical details (e.g., exact similarity threshold) could be condensed without loss.

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 fully compensates by detailing the response fields (opportunities[], partition_check{...}, fill check with realizable_edge_pp). It also covers edge cases (placeholder filtering, low similarity) and links to a sibling tool for advanced usage. The tool is completely described for agent 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% with brief descriptions, but the tool description adds substantial value: explains that event expects a slug and triggers child market traversal with specific checks, while topic triggers cross-event search with comparator. Also explains recommended use for each 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 explicitly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes between three call modes (no args, event, topic). It clearly identifies the tool's purpose and differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 for each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' Also explains when to avoid trading (realizable_edge_pp ≤ 0) and references a sibling tool for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description exceeds expectations by detailing caching ('Cached 1h at the KV level'), edge computation (net of slippage, per-model families), and response structure including diagnostics. 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 very long and dense, containing detailed technical explanations of model families and edge calculations. While informative, it could be more concise; the sheer length may overwhelm agents. Front-loading with the purpose helps, but some details like exact parameter values (e.g., 'tennis 1.02') are excessive for a summary.

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

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

Given the complexity (9 parameters, no output schema), the description thoroughly explains return values including per-opportunity fields (edge_pp_net, kelly_fraction, market stats) and top-level structure (by_segment, fed_candidates, _diagnostics). It also covers caching behavior and optional filters, making the tool fully understandable for 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%, providing baseline 3. The description adds significant context for some parameters (e.g., min_partition_leg_kelly explains why partition arbs have parent-level kelly=0 and how to filter per-leg). However, for most parameters, the description does not go beyond what the schema already provides.

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

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

The description clearly states the tool 'scan[s] top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and is built for 'what should I bet on today'. It is specific about the verb 'scan' and the resource 'Polymarket markets with Pipeworx data', but does not explicitly differentiate from sibling tools like polymarket_arbitrage, which may have overlapping 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 sets context by stating it is for discovering opportunities without paging, and includes exclusions like Fed bets being unreliable at meeting-month horizons. It implies when to use (daily betting decisions) but does not explicitly contrast with alternatives such as polymarket_edge_tracker or polymarket_arbitrage.

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 indicate read-only, idempotent, non-destructive behavior. The description adds context about data sources (snapshots, daily closes), constraints (60-day TTL, enabled date), and interpretation of 'decay' and 'edge_pp_net' sign. No contradictions.

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

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

The description is extremely information-dense but somewhat lengthy and uses a run-on structure for the response fields. It could be more concise by using lists, but every sentence is substantive.

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

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

Despite no output schema, the description fully explains the return format (tracked, expired, snapshot_dates arrays), field meanings (trend, decay_pp_per_day, lifespan_days), edge sign convention, and limitations. No gaps for this complex 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?

Both parameters have schema descriptions (100% coverage). The description adds valuable context: 'days' lookback with default/max, 'window' as snapshot family with default. It explains how these affect the data retrieved, going beyond schema docs.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge duration and shrinkage. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical tracking, not just current 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 gives a concrete example of when to use the tool (comparing fresh vs. old edges) and outlines the response structure. It does not explicitly mention alternatives or when not to use it, but the context is clear enough for 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context such as walking the ladder, returning slippage, fill details, and forced_directional_risk, which is consistent 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?

Well-structured with clear sections (SINGLE-MARKET, BASKET), bold emphasis, and no wasted sentences. The length is appropriate given the complexity of the tool.

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

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

The description covers return fields and limitations, but lacks an output schema. It gives a good overview, but could be more systematic in listing all return fields. Almost complete.

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

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

Though schema coverage is 100%, the description adds significant meaning: explains dual modes, parameter interactions (market vs event exclusive), default values, size_usd interpretation differences, and clamp range. This goes well beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check' against live order-book depth, and distinguishes between single-market and basket modes. It is a specific verb+resource that differentiates from sibling tools.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about theoretical overround not being capturable and partial basket fills converting arbs to directional positions.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description massively expands on that by disclosing limitation behavior: compatibility_codes, never-paired unknown legs, skipped_cross_type/subtype counters, temporal_alignment, and the caveat that pre-mapped topics often return warnings. This is a model of behavioral transparency — the description carries the burden beyond annotations and does so thoroughly, with no contradiction.

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

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

The description is long but structured in labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes). Every sentence carries unique, non-redundant information — from the spread range (2-25pp) to the meaning of each compatibility code. Core purpose and modes are front-loaded; lower-level flag behavior appears later. The density is justified by the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, skipped_unclassified, low_confidence_pairs, counters) and the conditions under which each appears. It also warns about the rarity of real spreads and the meaning of common codes. For a tool with this complexity, nothing an agent needs to interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between `topic` and the two override parameters (explicit ticker/slug override the topic-mapped side), the exact list of topic shortcuts, and the usage nuance that shortcuts are convenience mappings that may not be tradeable. This is meaningful semantic context beyond the schema descriptions.

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

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

The opening sentence names a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this from siblings like polymarket_arbitrage by framing the tool as cross-venue rather than within one venue. The description also enumerates exactly what the tool compares and in what units (Kalshi − Polymarket, pp), leaving no ambiguity about its function.

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

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

The description clearly explains two modes of use — `topic` shortcuts vs explicit ticker/slug — and when each is appropriate. It gives strong context about reliability: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it never names sibling alternatives (e.g., polymarket_arbitrage) or states when to use them instead, so the guidance is contextual but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds 'Keyless, offline' as extra behavioral context, but does not discuss edge cases like missing keys or invalid paths. Moderate value beyond annotations.

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

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

The description is very short, consisting of one sentence with an example. No wasted words, but could be slightly more structured. Effectively 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 tool with 2 fully described parameters and no output schema, the description is mostly complete. It covers the core functionality, example, and key behavioral traits (keyless, offline). Could mention error handling, but adequate.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds an example but no new semantic meaning 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 it extracts a value from JSON using dot/bracket notation, with a concrete example. It distinguishes from siblings like format_json and validate_json by specifying the action and resource.

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 mentions 'Keyless, offline', implying no auth or network needed, but does not explicitly state when to use vs alternatives or when not to use it. Usage context is somewhat implied by the sibling tools' purposes.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds scoping detail ('Scoped to your identifier') and the listing behavior when key is omitted. No contradictions.

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

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

Three sentences, all essential: action, use case, pairing advice. No wasted words. Front-loaded with the primary action.

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 both usage modes, scoping, and practical examples. Combined with clear annotations, it's fully complete.

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

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

Schema has 100% coverage for the single parameter. Description adds real-world context (e.g., 'user's target ticker, an address, prior research notes') and clarifies the dual behavior of retrieval vs listing, going beyond schema's generic description.

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

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

The description uses specific verbs ('Retrieve'/'list') and resource ('value saved via remember'/'all saved keys'). It distinguishes from siblings by name-dropping remember and forget, and gives concrete use examples (user ticker, address, notes).

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 ('look up context stored earlier'), why it's beneficial ('without re-deriving from scratch'), and how it pairs with siblings ('Pair with remember to save, forget to delete'). Also mentions scoping.

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, open-world, non-destructive. Description adds behavioral context: explains the mark_read flag's effect on next call, lists returned fields (source, citation_uri, payload). No contradictions.

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

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

Three sentences: purpose, return+parameters, advanced behavior and alternative access. Front-loaded, no fluff.

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

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

Covers return fields, key parameters, mark_read semantics, and polling suitability. Omits unread_only param description but schema handles it. No output schema, but description adequate for agent use.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: explains mark_read behavior, implies type filtering, notes limit range (1-200, default 50). Unread_only not mentioned but schema covers it.

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

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

Starts with 'Pull fired events from your subscription feed' – a clear verb+resource pair. Distinguishes itself from siblings like list_subscriptions by focusing on alert events and their payload.

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?

Clearly states the tool is for pulling recent alerts with optional filters. Mentions that polling works fine and provides an alternative endpoint for scripts/dashboards. No explicit when-not-to-use, but context is strong.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals that the tool fans out to multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains fallback behavior, and mentions soft-fail conditions (USPTO). This exceeds the annotation baseline.

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

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

The description is a single, well-structured paragraph that front-loads examples and key details. While efficient, it includes some redundancy with the schema descriptions of parameters, preventing a perfect score.

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

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

Despite lacking an output schema, the description explains the return structure (changes[ ] grouped by source, total_changes count, citation URIs). It covers parameters fully, addresses error conditions, and distinguishes from a sibling tool. For a tool with this complexity, no gaps remain.

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

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

Schema coverage is 100%, and the schema already contains detailed parameter descriptions (e.g., 'since' format with examples). The description adds no new parameter-level information beyond what is in the schema, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool serves as a change feed for a company, with examples like "What's new with X". It explicitly distinguishes itself from the sibling tool `entity_profile`, which provides static profiles.

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

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

The description provides explicit guidance on when to use this tool vs. alternatives (e.g., 'Use entity_profile instead when you want the static profile'). It includes example queries and context for typical usage.

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

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

Annotations indicate idempotent and non-destructive. Description adds that data is key-value scoped by identifier, with persistent memory for authenticated users and 24-hour retention for anonymous sessions. No contradictions.

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

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

Three concise sentences cover purpose, usage, and behavioral details. Front-loaded with verb and resource, 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?

No output schema, but description explains storage behavior and pairing with recall/forget. Could mention return value (e.g., success confirmation), but still complete for a simple save operation.

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

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

Schema coverage is 100% with descriptions for key and value. Description provides examples but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description states 'Save data the agent will need to reuse later', specifying the verb (save) and resource (data). It distinguishes from sibling tools recall and forget, which are mentioned as pairs.

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 advises when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). Also details scoping by identifier and persistence duration.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses key behavioral traits: graceful degradation of LEI/FIGI enrichment, explicit reporting of unresolved identifiers under `unresolved`, and internal cascading through multiple endpoints. This gives agents a precise model of what to expect.

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 carries essential information about usage, supported types, fallback behavior, and source labeling. It is front-loaded with the core purpose and usage directive, though the density is high and could be slightly streamlined without losing value.

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

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

The tool's complexity (two entity types, multiple identifier systems, fallback logic) is fully covered. Since there is no output schema, the description compensates by describing resolved identifiers, source labeling, unresolved handling, and even provides a cite URI example for drugs, making it self-sufficient for an agent.

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

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

The schema already documents both parameters, but the description adds substantial semantic depth: it expands accepted value formats for company (ticker, CIK, ISIN, name), explains ISIN-to-LEI mapping for non-US issuers, and details the drug return payload (RxCUI + ingredient + brand). This goes beyond the schema's simple 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 clearly states the tool's core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides multiple concrete query examples and explicitly lists supported types (company, drug), distinguishing it from general lookup tools.

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

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

It provides an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This gives clear when-to-use guidance, though it does not name alternative tools or explicitly state when not to use. Still, the 'FIRST' instruction strongly positions the tool as the initial step for name-to-ID resolution.

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 behavior. The description adds transparency by revealing that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. 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?

Two sentences, front-loaded with the main purpose, no wasted words. Every sentence adds 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?

With 4 parameters and no output schema, the description adequately explains the tool's function and output format. It mentions the ranked list with three fields, which is sufficient for an agent to understand the result. Could be more detailed, but acceptable.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal context (first entity treated as subject) but does not significantly elaborate beyond the schema.

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

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

The description clearly states the verb 'Compare AI visibility' and the resource 'multiple entities'. It explicitly names the internal tool ai_visibility_check and mentions ranking by score, distinguishing it from sibling tools like compare_entities by focusing on AI visibility.

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: 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use but does not explicitly mention when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds critical behavioral details: partial failure degradation, bundlephobia's first measurement taking 5-30s, and the sources_failed field. This goes beyond the structured annotations.

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

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

The description is a single dense paragraph containing all essential information: purpose, usage, limitations, and return structure. Every sentence contributes value, but it could be slightly restructured for clarity (e.g., bullet points). Efficient overall.

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?

No output schema exists, so description bears full burden. It lists all return fields (summary block fields, per-advisory detail, links, alternative versions) and explains partial failure behavior. This is fully sufficient for an agent to understand what the tool returns.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the package name scoping and version defaults already present in the schema, adding no new parametric meaning. Agent gets no extra value from description regarding parameters.

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

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

The description clearly states the tool is a composite check for adding npm packages, combining data from deps.dev and bundlephobia. It specifies the exact purpose: evaluating safety, popularity, size, and cost. This distinguishes it from siblings like 'entity_profile' which are more general.

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 says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes the NPM-only limitation for v1. While it doesn't name an alternative tool for other ecosystems, it indirectly points to deps.dev for those. This is clear context but lacks explicit exclusion.

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 readOnly/idempotent annotations, description details BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Completely transparent about internal mechanics.

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?

Front-loaded with core purpose, then expands with usage and technical details. Each sentence adds unique value, though slightly dense. 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, description adequately explains return format (passages with offsets and similarity scores) and input limits (200K chars, truncation). Fully informs agent of expectations.

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

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

Schema covers all parameters descriptively. Description adds value by giving natural-language query examples and stating the text parameter is for already-pulled content. Enhances schema without redundancy.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). It distinguishes from siblings by mentioning 'ask_pipeworx_grounded' as a pair, making it unique among sibling tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with 'ask_pipeworx_grounded'. No explicit when-not scenarios, but context is clear enough.

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 indicate idempotentHint=true and destructiveHint=false, but the description adds significant behavioral context: requires OAuth account, returns subscription id, delivery constraints (phone verification, 10/day SMS cap, webhook auto-disable after 10 failures). 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 well-structured: purpose first, then requirements, type details, delivery channels. It is informative but somewhat lengthy; could be slightly more concise without losing clarity.

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 3 parameters with full schema coverage, no output schema, the description covers all necessary aspects: return value, type-specific filters, delivery options with constraints, and prerequisites. Highly complete for a subscription creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with type-specific examples and delivery channel constraints, providing meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and specifying supported types and delivery channels.

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 context on when to use this tool (create subscription) and who can use it (requires Pipeworx OAuth account, excluding anonymous/BYO). It details type-specific conditions, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return format (category-bucketed example questions) and that results are drawn from a live catalog of thousands of tools, plus the onboarding entry point context. 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 front-loaded with example questions and is comprehensive without being overly verbose. Every sentence adds value, though it could be slightly more concise by combining some elements. Still, it earns its length.

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

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

Given the single optional parameter, no output schema, and rich annotations, the description thoroughly explains the tool's purpose, usage, and return format. It covers when to use it, how to invoke it, and what to expect, making it complete for an agent.

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

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

Schema coverage is 100% with a description for the topic parameter. The description adds meaning beyond the schema by explaining that omitting the argument gives a full spread and listing possible topic values (finance, pharma, etc.). This provides practical usage context.

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

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

Description clearly identifies the tool as the onboarding entry point for Pipeworx, listing example user queries and explicitly stating what it returns (category-bucketed example questions with exact tool+argument shapes). It provides a specific verb+resource and distinguishes from sibling tools like ask_pipeworx and discover_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?

Explicitly states when to use this tool: '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 gives guidance on arguments, such as omitting the topic parameter for a full spread or passing a specific topic to focus.

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

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

The description discloses that the row is deactivated (not deleted), which is important behavioral context beyond annotations. It also states ownership enforcement, adding value.

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 efficient sentences, front-loaded with purpose. Every sentence is necessary and adds value, no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraints, behavioral effects, and parameter source, making it fully complete.

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

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

Schema coverage is 100%. The description adds 'returned by subscribe' linking parameter to a sibling tool, providing extra context 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 'Cancel a subscription by id.' with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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 mentions ownership enforcement ('you can only cancel your own subscriptions') and the deactivation effect. While it doesn't provide explicit when-not-to-use or alternatives, the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: it defines the verdict taxonomy (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), explains the verification_error structure, and warns that could_not_verify must not be treated as evidence. This enriches the safety and failure-mode understanding beyond what annotations alone 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 thorough and well-structured but somewhat long. It front-loads trigger phrases, then explains routing, return values, and special caller warnings. Each sentence adds value, though the 'IMPORTANT for callers' clause could arguably be merged with the verdict definitions to reduce redundancy. Overall, it's efficient for a tool with this complexity, so a 4 is appropriate.

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 fully explains return values: a verdict, the actual value with a pipeworx:// citation, and reasoning. It also explains error handling (could_not_verify with verification_error) and differentiates unsupported. It covers both financial and non-financial routing and mentions tolerance semantics. This is complete for a verification tool with these inputs and annotations.

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

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

Schema coverage is 100%, with both claim and tolerance_pct fully documented in the schema. The description adds examples but does not introduce new parameter semantics beyond what the schema already states (e.g., tolerance_pct range and override behavior). Per the rubric, baseline 3 is appropriate when schema does the heavy lifting, and the description doesn't compensate with extra details.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources. It lists trigger phrases like "Is it true that…" and "fact check," and explains the two paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for others). This distinguishes it from sibling tools like compare_entities or ask_pipeworx_grounded by explicitly stating what it verifies and how.

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 whenever the agent needs to check whether something a user said is factually correct." It also clarifies the meaning of special verdicts (could_not_verify vs unsupported) and notes that it replaces 4–6 sequential calls, giving efficiency context. No exclusions are needed because it covers both financial and non-financial claims through routing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details about returning validity and error info, which goes beyond annotations. No contradictions.

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

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

The description is a single, clear sentence with no redundant information. It is front-loaded with the purpose and efficiently covers key details.

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

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

For a simple validation tool with one parameter and no output schema, the description sufficiently covers purpose and return values. It could mention common pitfalls like input escaping, but overall it is adequate.

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

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

Schema coverage is 100% with a clear description for the json parameter ('The JSON text to validate'). The description adds the qualifiers 'keyless, offline' which provide minor additional context but are not critical given the 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 verb 'Validate' and the resource 'JSON string', and specifies that it works offline and returns validity, error message, and character position. It effectively distinguishes from sibling tools like format_json and query_json.

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

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

The description implies usage for validating JSON strings offline and without keys, but does not explicitly state when to use this tool over alternatives like format_json or query_json, nor does it mention when not to use it.

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