Data Norfolk

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behavioral details: default model is free Workers AI Llama, API key needed for Anthropic, and return format (per-model score, confidence, signals, raw_response plus combined view). No contradictions with annotations.

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

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

The description is about 4 sentences, well-structured with front-loaded purpose. It efficiently communicates key info without verbosity. Could be slightly tighter but still good.

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

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

Given the tool's complexity (4 params, no output schema, rich annotations), the description covers use cases, parameter nuances, return format, and model options. It provides enough for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: explains the default model, that _apiKey is only needed for Anthropic, and that context helps disambiguate. This adds value beyond the schema.

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

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

The description clearly states what the tool does: probe LLMs for knowledge about an entity and score visibility. It uses a specific verb (probe), identifies resources (LLMs), and describes output (score per model). It distinguishes itself from sibling tools like ask_pipeworx and bet_research by focusing on AI visibility audits.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use (visibility checks) and provides context but does not 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?

Annotations already declare read-only, open-world, idempotent behavior. The description adds meaningful behavioral context beyond those hints: it fills in arguments automatically, selects from 5,798 tools across verified sources, and returns stable pipeworx:// citation URIs. No contradiction with annotations exists.

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 most important directive ('PREFER OVER WEB SEARCH') and follows with mechanism, use cases, and examples. It is somewhat long and repeats 'current or historical data' and the same trigger-phrase idea, but the length is mostly justified for a broad routing 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?

It covers the tool's scope, mechanics, input style, and return format (structured answer plus stable citation URIs), which is strong given there is no output schema. It doesn't specify failure behavior, such as what happens when no matching source exists, but that is not a required gap for a read-only router.

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

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

The input schema already fully documents the single core parameter question and its aliases, so the baseline is 3. The description adds value by making clear that the user should provide broad natural-language questions and that the tool handles the underlying argument construction, aided by several representative 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 identifies a distinct purpose: routing natural-language factual questions to the best source tool and returning cited structured answers. It names the resource (Pipeworx) and the verb-space ('routes', 'fills arguments', 'returns'), making the tool's function unmistakable. However, it does not differentiate from closely named siblings like ask_pipeworx_beta or 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 strong, explicit guidance on when to use it: prefer it over web search for factual/current/historical data questions, and it lists trigger phrases and concrete examples. It lacks explicit when-not-to-use guidance or alternative tool names beyond web search, so it misses the full 5.

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

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

With annotations already covering read-only, idempotent, open-world, and non-destructive behavior, the description adds meaningful context beyond them: current no-candidate state, the retirement date of the last candidate, and the explicit clarification that this is a full working router with no fallback. This is unusually transparent.

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

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

Every sentence earns its place: identity and scope, current candidate status, usage guidance, and a clarifying note about fallback. It is front-loaded with the core 'beta version of ask_pipeworx' framing and avoids redundant restatements of the schema or annotations.

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 routing tool with a single required question parameter and no output schema, the description covers invocation, behavior, current state, and relationship to alternatives. It tells the agent the response shape matches ask_pipeworx and that no candidate is active, so nothing essential is missing.

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

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

The input schema already documents all six parameters with 100% coverage, including the aliases, so the description does not need to repeat them. It does add that the tool takes the same arguments as ask_pipeworx, which is useful for cross-referencing, but it doesn't deepen the semantics of the parameters themselves.

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, an identical universal router with the same 5,798 tools, arguments, and response shape. It also states its unique purpose: exposing candidate routing improvements for live testing. This distinguishes it from the stable ask_pipeworx sibling and gives an agent specific grounds for selecting it.

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 to 'Use it exactly like ask_pipeworx when you want the newest routing', naming the alternative and the condition that selects it. It also notes that results are compared against the stable router to decide what merges, giving clear operational context.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the extra LLM call cost, the exact refusal schema, and the constraint that extraction uses only the tool result. It also names concrete refusal_reason values, making failure modes predictable. None of this is contradicted by readOnlyHint, openWorldHint, or idempotentHint.

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

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

The description is dense but not bloated; every clause supports either the core purpose, the routing distinction, or the when-to-use guidance. It front-loads the most important trait (hallucination-resistance) and then builds toward usage guidance. It is slightly longer than the minimal ideal, but the added complexity is justified by the refund output contract.

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

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

Even without an output schema, the description fully specifies success and refusal return shapes, enumeration of refusal reasons, routing behavior, cost tradeoff, and usage boundaries. An agent has everything needed to decide to use it, invoke it, and interpret its response in a high-stakes 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 description coverage is 100% and the single conceptual parameter ('question') has several documented aliases. The description adds no new parameter-level detail, but it doesn't need to since the schema fully documents the input. This matches the baseline expectation of 3 when the schema carries the parameter documentation burden.

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

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

The description clearly names a specific capability ('hallucination-resistant answer mode') and a specific resource ('ask_pipeworx' routing). It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior. An agent can immediately understand what tool this is and when it differs from the obvious alternative.

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: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete high-stakes domains. It also provides an explicit exclusion and alternative: 'prefer ask_pipeworx for casual lookups,' including the cost tradeoff. This is model routing guidance, not just a feature summary.

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?

Describes numerous behaviors: market resolution, classification, fan-out, edge cases (low confidence, closed markets, wide spreads), cancellation rule parsing, and safety mechanisms. Annotations declare read-only and idempotent, which are consistent and complemented by description.

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?

Very detailed but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). Slightly verbose but justified by the tool's complexity; front-loads essential 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?

Covers all necessary context: input format, output shape (including nested fields like result.market, result.analysis, result.evidence), error states (low_confidence_match, market_closed_or_inactive), and safety guidelines. No output schema exists, so description fully compensates.

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?

With 100% schema coverage, the description adds rich semantic detail: explains the market parameter accepts slug, URL, or question text; describes depth options (quick vs thorough) and include_raw flag with trade-offs.

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

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

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data. Provides specific verb (research), resource (Polymarket bet), and scope (via market slug/URL/question text). Distinguishes from siblings by its focused 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?

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it doesn't directly contrast with sibling tools, the specificity makes selection 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads triggers. Every sentence adds value, but it could be slightly more structured (e.g., bullet points) for easier scanning. Still, it is concise given the 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?

Despite no output schema, the description explains the return (paired data + citation URIs). It covers inputs, behavior, and output structure. Missing details on error handling or missing entities, but for the complexity level, it is fairly 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%, providing baseline 3. The description adds value by explaining enum options (company vs drug), format for values array (tickers/CIKs vs names), and constraints (2-5 items). It also gives examples, enhancing semantics beyond schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes from sibling tools like entity_profile (single entity) and search tools by emphasizing its comparative nature and efficiency.

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 advises to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, providing clear usage context. It also gives example triggers. However, it does not explicitly state when not to use it or list alternatives, though the context implies it's for comparisons only.

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. Description adds return format details (resource_id, name, description, category, update date) and pagination hints, complementing annotations 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?

Single sentence, no wasted words, front-loaded with action and resource, efficient.

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

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

Given no output schema, description lists return fields. Parameters are fully described in schema. Provides enough context for the agent to understand usage and results.

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

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

Schema coverage is 100%, so the schema already explains parameters. Description adds minor context: 'keyword' for query, pagination for offset, but does not significantly enhance semantics beyond schema.

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

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

Description clearly states 'Search the Norfolk Open Data catalog of open datasets by keyword', specifying verb and resource. It differentiates from sibling 'metadata' by noting to pass resource_id to that 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?

Provides clear context on when to use: search by keyword. Mentions post-use action (pass resource_id to metadata), but lacks explicit when-not or alternative usage beyond this hint.

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

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

The annotations cover read-only/idempotent safety, but the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition, never-invented gaps[], contradictions[] scanning, fetchable citation URIs, semantic excerpting, and latency expectations. This is additive and consistent with the annotations.

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

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

Dense and front-loaded with the most operationally important facts: account requirement and the ask_pipeworx fallback. It is long, but nearly every sentence earns its place given there is no output schema and the depth tiers have real behavioral nuance.

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

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

With no output schema, the description fully compensates by specifying the return shape: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers auth, timing, and how unanswerable facets are handled, so an agent can invoke with realistic 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?

The schema already documents both parameters with 100% coverage, including detailed depth enum semantics. The description reinforces that question should be broad/multi-part and links depth tiers to hop/recovery behavior, adding useful context even though the schema carries most of the parameter burden.

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

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

States a specific action — grounded multi-source research in one call — over clearly identified structured data source classes (SEC, FRED/BLS, FDA, USPTO, etc.). It also explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell what this tool is for.

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

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

Gives explicit routing guidance: if not signed in, use ask_pipeworx instead; for a single lookup, use ask_pipeworx; best for broad/multi-part structured-data questions. This is positive and negative guidance with named 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral context about returning top-N relevant tools with full schemas ready to call, which goes beyond annotations. 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 a single paragraph, front-loaded with purpose, every sentence adds value: purpose, usage examples, output description, strategic guidance. No wasted words.

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

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

Despite no output schema, the description explains the return format comprehensively: top-N tools with names, descriptions, full input schemas. It also covers parameter semantics through examples and aliases. Complete for a discovery 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 meaning by providing natural language examples for the query parameter and explaining that multiple aliases are accepted, which enhances understanding 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 finds tools by describing the data or task. It uses specific verb 'find' and resource 'tools', and distinguishes from siblings by advising to call it first when needing to browse the tool set.

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 you need to browse, search, look up, or discover what tools exist for' with specific examples. Also advises to call it FIRST when many tools are available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark this tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: sources_used/sources_failed semantics, empty sections meaning real absence of data rather than bugs, patents soft-failing, FDA data being absent for small-molecule-only companies, and private companies returning resolved:false with notes. This is exactly the kind of nuance an agent needs to interpret results safely.

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 examples and the ALWAYS PREFER directive, which is good, but the middle is a dense semicolon-separated stream of source and return-field details that would be far easier to parse as structured bullets. Several opening examples and the final type-equivalence sentence duplicate information already present in the schema, so not every sentence earns its place.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it lists the main fields, source-specific outputs, URIs, no-data behavior, and private-company failure mode. An agent has enough context to call the tool correctly and interpret both successful and empty responses.

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

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

The input schema already documents the same value forms (ticker, zero-padded CIK, company name), SEC EDGAR name resolution, and the interchangeable type behavior, so schema coverage is effectively 100%. The description repeats these details and adds the resolved:false private-company edge case, but it does not substantially change parameter comprehension 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 opens with concrete user-phrase examples and immediately states the tool's core purpose: a full cross-source profile of a US public company in one call. It clearly differentiates itself from chaining single-pack SEC/XBRL/news lookups, so an agent can tell when this tool is the right high-level 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?

The description explicitly says to prefer this tool over chaining single-pack lookups when the user wants a holistic view, which is actionable usage guidance. It also explains accepted input forms and the private-company resolved:false behavior. However, it does not name specific sibling tools or provide exclusion criteria such as 'use compare_entities instead for multi-entity comparison,' so it stops short of a full when-not-to-use map.

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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing with other tools, but does not significantly extend beyond what annotations convey.

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

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

The description is two sentences long, with no wasted words. It is front-loaded with the core action and immediately provides usage guidance.

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 context, and relationships with siblings completely. No additional information is needed.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter as 'Memory key to delete'. The description adds 'by key' but does not provide additional meaning beyond the schema.

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

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

The description explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall', both mentioned in the description.

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

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

The description provides clear usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall', but does not explicitly mention 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?

Annotations indicate readOnlyHint, idempotentHint, destructiveHint false. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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 concise with a clear front-loaded purpose statement. Some slight redundancy (e.g., listing AI crawlers) but overall efficient and each 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?

Given the simple tool with 2 parameters and no output schema, the description adequately explains input, process ('fetches, extracts, emits'), and output ('single text blob in markdown format'). Includes practical use cases.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description mentions 'key links' in context but adds minimal additional meaning beyond the schema's parameter 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 generates an llms.txt file for a URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on the specific output format and use cases.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not mention when not to use the tool or explicitly contrast with alternatives like 'scan_competitor_ai_presence'.

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, covering safety. The description adds the list of returned fields, but does not disclose additional behavioral traits like pagination or default limits.

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 concise: two sentences that front-load the action and resource, followed by return fields and usage guidance. No unnecessary information.

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

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

For a simple listing tool with one optional parameter and good annotations, the description is nearly complete. It could mention pagination or ordering, but those are minor omissions given the tool's simplicity.

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% (only one parameter with a description). The tool description does not add extra meaning beyond the schema's parameter description, so it meets the baseline for high 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 specifies the action ('List'), the resource ('the caller's active subscriptions'), and lists the returned fields, which distinguishes it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clarifies when to use the tool, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false, indicating safe read-only behavior. The description adds that it returns schema and metadata details, providing additional context about the return value but not contradicting or significantly extending 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, well-structured sentence that starts with the core action and includes an example. It is concise with no superfluous information.

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

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

For a simple metadata retrieval tool with one parameter, the description covers the main functionality and return value. It could briefly mention error handling for invalid resource IDs, but overall it 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 the parameter is fully documented in the schema. The description reinforces that the resource_id is a dataset ID and provides an example, but does not add meaning beyond the schema.

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

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

The description clearly states the tool retrieves a dataset's schema and metadata, listing specific attributes (columns, types, row count, category, last-updated). It provides an example resource ID, distinguishing it from siblings that do not specifically target Norfolk Open Data metadata.

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 example usage but no explicit guidance on when to use this tool versus alternatives. It does not state prerequisites or conditions for appropriate use.

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

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

The description discloses non-obvious behaviors beyond the annotations: rate-limiting ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token mechanism for checking resolution status. This gives the agent crucial context that the all-false annotations do not convey.

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

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

The description is front-loaded with the core purpose in the first sentence. While lengthy, every subsequent sentence contributes unique operational information (what to report, where to report alternatives, token flow, rate limits, cost). It is dense but not wasteful; a slight trim would make it more 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?

Despite having no output schema, the description fully anticipates agent needs: it explains the return behavior (claim_token for anonymous filing, status readback), clarifies scope boundaries, and even notes the team's daily digest and roadmap impact. The tool's 0 required parameters and 4-parameter nested schema are fully contextualized.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage context: advising agents to describe issues in terms of Pipeworx tools (not paste end-user prompts) and explicitly explains how to use the claim_token parameter ('pass the pwfb_… token ... with no other arguments'). This is a clear value-add over the schema.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the exact feedback categories (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling research/query tools by being the only feedback channel.

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

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

Provides explicit when-to-use rules for each feedback type and an explicit exclusion: tools from other MCP servers should be filed elsewhere. It even gives a disambiguation test ('Pipeworx tool names are the ones this connection lists'), making it unambiguous for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable contextual information: data source (CF analytics-engine), privacy (no PII), and caching details (5min-1h depending on window). This goes beyond the annotations without contradicting them.

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

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

The description is well-structured with a clear purpose, use cases, and additional context. Each sentence adds value, though it could be slightly more concise by merging some clauses. Overall, it's efficient and easy to parse.

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

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

Given the tool has only one optional parameter and no output schema, the description adequately explains the return format (top tools, top packs, total call volume) and caching behavior. It provides enough context for an agent to understand and invoke the tool correctly.

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

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

The input schema has 100% coverage with a description for the 'window' parameter and enum values. The description adds extra meaning by explaining that shorter windows surface hot trends while longer windows show steady-state demand, which helps an agent choose the appropriate window.

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 returns top tools, top packs, and total call volume over configurable windows (24h, 7d, 30d). This uniquely distinguishes it from sibling tools like 'discover_tools' or 'ask_pipeworx' which serve different purposes.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and mentions caching behavior. While it doesn't state when not to use it, the context is clear and helpful for an agent deciding whether to invoke this tool.

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

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

Description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false). Adds rich behavioral details: algorithms (monotonicity violations, partition-sum checks), thresholds (3pp, 0.30 Jaccard, 20% placeholder), fill check logic, and response structure. 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?

Dense with information but well-organized (modes marked by backtick keywords, sections like FILL CHECK). Slightly verbose but every sentence contributes; minor room for tightening.

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 tool behavior comprehensively: default scan, two modes, algorithms, constraints, fill check, and references to sibling tool. Lacks output schema but compensates by detailing response fields. Fully adequate given complexity.

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

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

Schema coverage is 100%, and the description significantly enhances understanding: defines event slug, topic as seed question, explains behaviors like automatic slug resolution and cross-event search. Goes far beyond schema descriptions.

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

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

Uses specific verbs ('Find arbitrage opportunities') and resources ('Polymarket') with clear differentiation between modes (trending_scan, event, topic). Distinguishes from sibling tools that handle edges, fill risk, or spreads.

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: no args for trending_scan, 'event' for single-event slug, 'topic' for cross-event. Explains when to use each and what they achieve. Also references polymarket_fill_risk 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 declare readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: caching at KV level for 1h, detailed explanation of model segments, edge calculations, and filter skips via _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 lengthy but well-structured with numbered segments and explanatory notes. Every sentence adds value, but the verbosity may hinder quick parsing by an AI agent. It could be more 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?

Despite no output schema, the description fully explains the response structure: by_segment with three groups, fed_candidates, and _diagnostics. It covers caching, edge calculations, filter behavior, and all important aspects for effective tool usage.

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

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

Schema coverage is 100% with detailed parameter descriptions. The overall description adds extra context, e.g., explaining how min_partition_leg_kelly applies to per-leg Kelly inside partitions. This goes 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 description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement and including multiple model families.

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 it is built for 'what should I bet on today' and mentions tradeable-edge knobs (min_liquidity, max_spread_pp). It also explains that Fed bets are excluded from ranking. However, it lacks explicit alternatives or when-not-to-use scenarios.

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, etc. Description adds detailed output explanation, decay computation method, and snapshot TTL bounds, going 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?

Front-loaded with purpose, followed by detailed output structure. Slightly verbose with 'RESPONSE:' section but each sentence adds value. Could be trimmed marginally.

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 fully explains return value fields with examples and edge cases (expired, gaps). Limitations on TTL and intraday vs daily are covered.

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 parameters with descriptions. Description adds constraint 'max 30' for days (schema says 'clamp 2-30') and enumerates window options (24hr, 1wk, 1mo) beyond schema's simple 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 explicitly states it provides 'edge persistence and decay telemetry' and answers a clear question. It distinguishes from sibling 'polymarket_edges' by focusing on time-series and trends.

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

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

Implied usage context is given ('a fresh wide edge and a 3-week-old wide edge are different trades'), but no explicit when-to-use versus alternatives like 'polymarket_edges' or 'polymarket_arbitrage'. Limitations are mentioned, but guidance is incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable behavioral details: walks order-book ladder, returns verdict (clean/degraded/cannot_fill), highlights forced directional risk and thin legs. 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?

Slightly long but well-structured with clear sections, bold headers, and bullet-like formatting. Front-loaded with purpose. Every sentence earns its place, no wasted words. Could be more concise but appropriate for 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?

No output schema, but description lists all return fields for both modes, including edge cases (thin_legs, forced_directional_risk). Covers defaults, clamping, and mode selection. Fully equips agent to understand tool's behavior and output.

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. Description adds meaning beyond schema: clarifies size_usd for basket as settlement notional (shares per leg), explains default side auto-logic, and details single-market side options. Adds substantial value.

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

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

The description clearly states it checks realizable-vs-theoretical edge against live CLOB depth, distinguishes single-market and basket modes, and lists specific return fields. It directly contrasts with siblings by advising use before polymarket_arbitrage or polymarket_edges, making purpose distinct.

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

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

Explicitly states when to use: before acting on arbitrage signals or edges trades above ~$500. Provides rationale about capturability and risk of partial fills turning arb into directional position. Clearly guides the agent on appropriate context.

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

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

The description is exceptionally transparent about behavior beyond the annotations: the same token-overlap matcher runs in both modes, compatibility_warning/codes are not mutually exclusive with matched_pairs, unknown legs are never paired, temporal_alignment null means uncomputable rather than aligned, and fees are gross not net. This far exceeds what the readOnly/idempotent/openWorld annotations provide and gives the agent accurate expectations about edge cases.

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

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

The description is long but tightly organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence carries meaningful caveats or operational detail. It front-loads the core purpose and mode selection before diving into safety codes and skipped-leg counters. Given the complexity of cross-venue matching, this length is earned rather than padded.

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

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

Despite having no output schema, the description thoroughly documents the response shape: leg prices, matched spreads, top_spreads_pp with per-entry flags, compatibility fields, temporal_alignment object, fees_note, and skip counters. It also covers failure semantics and practical reliability caveats. An agent has enough context to invoke the tool and interpret results correctly without additional documentation.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the raw property descriptions. It explains the relationship among topic, kalshi_event_ticker, and polymarket_event_slug, states that explicit parameters override the topic-mapped side, and clarifies that both modes execute the identical matcher. It also explains the consequences of leaving all parameters empty, which the schema alone does not convey.

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

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

The description clearly identifies the tool's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains both operational modes (topic shortcuts and explicit pairings) and the core output concept. It does not explicitly distinguish itself from similar sibling tools like polymarket_arbitrage or polymarket_edges, so it misses the explicit sibling differentiation needed for a 5.

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

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

The description gives clear operational context: when to use topic mode vs explicit mode, what the pre-mapped shortcuts are, and that custom ticker/slug overrides the mapped side. It warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly state 'use X instead when...' for sibling tools, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of returning JSON adds minimal extra transparency. No behavioral quirks beyond what annotations cover are disclosed.

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

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

Two sentences concisely convey purpose, syntax, and output. The action verb 'Run' is front-loaded, and no extraneous words are present.

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 7-parameter tool with no output schema, the description adequately covers the purpose and usage. It could mention that not all parameters are required, but the schema already indicates required fields.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by clarifying that SoQL clauses should omit the leading $ and provides an example, enhancing understanding 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 runs a Socrata SoQL query against a specific dataset identified by resource_id. It lists the filter clauses and return format, making the purpose unambiguous. No sibling tool appears similar.

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

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

The description explains how to use the tool (with SoQL clauses and limit/offset) but does not explicitly state when not to use it or suggest alternatives. Sibling 'datasets' implies listing datasets, but no direct exclusions are given.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: scoping to user identifier, behavior of omitting key (list all), and pairing with remember/forget. It aligns with annotations and discloses behavioral traits beyond them.

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

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

The description is two sentences, front-loaded with the core action, and efficiently covers purpose, usage, scoping, and pairing without unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately covers retrieval, listing, scoping, and pairing. Minor gap: does not describe return format or behavior on missing key, but these are typical omissions.

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 input schema already documents that omitting the key lists all keys. The description only repeats this information, adding no new parameter semantics 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 clearly states the tool retrieves a value saved via remember or lists all saved keys when key is omitted. It distinguishes from siblings remember and forget, and specifies the resource (saved values) and verb (retrieve/list).

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 advises using recall to look up previously stored context without re-deriving it, and pairs it with remember/forget. It provides clear context but does not explicitly state when not to use it or compare to other sibling tools beyond the memory trio.

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 readOnly, openWorld, idempotent, non-destructive. Description adds that mark_read affects next call, and the feed is also available via HTTP GET. This adds useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Every sentence earns its place.

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

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

With 5 optional parameters and no output schema, the description adequately covers return fields, filtering, and side effects (mark_read). Could mention rate limits or pagination, but sufficient for usage.

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%. Description adds value by providing example filter ('sec_8k'), clarifies mark_read effect, and explains since as ISO timestamp. No enums needed.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies return fields (source, citation_uri, raw payload), and differentiates from siblings by focusing on alert retrieval with filtering. No sibling confusion.

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

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

Describes when to use (for recent alerts), how to filter (type, since, mark_read, unread_only), and notes polling works fine. Mentions alternative access via GET endpoint. Does not explicitly state when not to use, but provides sufficient context.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses significant behavioral detail: it fans out to three sources with fallback logic, returns structured changes grouped by source with citation URIs, and handles relative date shorthand. No contradictions with annotations.

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

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

The description is concise yet comprehensive. It front-loads the user-facing purpose with example queries, then methodically covers sources, parameters, fallbacks, and alternatives. Every sentence adds value without redundancy.

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

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

Given no output schema, the description covers return structure (changes grouped by source, total_changes count, citation URIs), all input semantics, source behaviors, failure modes, and when to choose an alternative tool. It is fully complete for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, but the description adds valuable context beyond the schema: it clarifies that `since` accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y'), provides examples, and recommends typical monitoring windows. This enriches the parameter understanding.

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

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

The description is explicit: 'change feed for a company in the last N days/weeks/months' with concrete example queries ('What's new with X', 'latest on Y'). It clearly distinguishes from the sibling tool entity_profile by specifying when to use the alternative.

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 excellent usage guidance: it explains the fallback chain (GDELT→GNews), the USPTO soft-fail, and explicitly states when to use entity_profile instead for static profiles. It also recommends typical window values like '30d' or '1m'.

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. The description adds context: key-value scoping, 24-hour retention for anonymous, and cross-session memory. 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 front-loaded with purpose. Concise but could be slightly tighter; no unnecessary 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?

Covers scope, persistence, related tools, and use cases. No output schema needed for a simple store; annotations cover idempotency.

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 good parameter descriptions (examples for key, value as 'any text'). The description reinforces key-value concept but adds minimal new parameter-specific info.

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: 'Save data the agent will need to reuse later'. It specifies the resource as key-value data, distinguishes from siblings (recall, forget), and explains scoping by identifier.

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: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, and explains persistence differences for authenticated vs anonymous users.

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

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

Annotations already mark this as read-only, open-world, and idempotent, and the description adds substantial context: identifier sourcing, explicit `unresolved` output, graceful degradation for LEI/FIGI, internal cascading across endpoints, and ambiguous matches returning `figi_candidates`. This goes well beyond the annotations and clarifies exactly how the tool behaves.

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

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

The description is long but well-structured: example queries come first, followed by usage guidance, then per-type details. Almost every sentence adds information, though some redundancy with the schema and the very long parenthetical could be tightened without losing meaning.

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 what will be returned for both supported types, how sources are labeled, what happens on ambiguous matches, and how failures are surfaced (`unresolved`). Combined with annotations, an agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds critical value beyond the schema: it explains the 'entity name only' rule, warns that trailing security-class words will not match in FIGI lookups, gives examples of accepted inputs (ticker, CIK, ISIN, brand/generic names), and clarifies ISIN-to-LEI behavior. This materially improves correct invocation.

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

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

The description specifies the verb 'resolve' and the resource: user-spoken names to canonical identifiers required by other tools, with example queries and supported types. It does not explicitly name a sibling tool to distinguish from (e.g., entity_profile), so it is clear but lacks direct sibling differentiation.

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 clear directive: 'Use FIRST whenever you have a name but need an ID,' and adds that one call replaces 2-3 manual lookups. It does not explicitly say when not to use this tool or name an alternative, so it stops short of the strongest when-to-use guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it probes each entity using ai_visibility_check, ranks by score, and surfaces most/least recognized. It also describes the return format (ranked list with score, confidence, signal density), which is essential without an output schema.

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

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

The description is two sentences long. The first sentence immediately states the core action and output. The second sentence provides a use case and specifies return fields. No wasted words – each sentence earns its place.

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

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

Given no output schema, the description sufficiently explains output fields (score, confidence, signal density). It covers the main purpose, parameters, and use case. However, it omits potential error conditions or rate limits, but annotations and schema cover safety and idempotency. It is adequate for an agent to use correctly.

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

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

Schema coverage is 100% with clear descriptions. The description adds meaning beyond the schema: it clarifies that entities are 'brand/business/product names' and that the first entry is treated as the 'subject' for narrative. This helps the agent understand the intended use of the 'entities' 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 uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly states the main action (probes each entity, ranks by score), and provides a concrete use case example. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different comparison type).

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

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

The description explicitly states the tool is 'useful for competitive AI-marketing audits' and gives an example question. However, it does not explicitly tell the agent when not to use it or mention alternatives like ai_visibility_check for single entities. 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, openWorldHint, idempotentHint true. Description adds behavioral detail beyond annotations: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' 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?

Description is detailed but every sentence adds value, including purpose, usage, return content, limitations, and error handling. Slightly long but well-structured and 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?

Despite no output schema, description thoroughly explains return format: 'summary block... per-advisory detail, links, and a list of recent alternative versions.' Also covers partial failure behavior. Complete for a 2-param 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% with descriptions for both parameters. Description adds context: default version behavior ('Defaults to the latest published version when omitted') and scoped package acceptance, providing value beyond schema.

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

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

Description starts with a clear verb phrase 'Composite should I add this npm package to my project check' specifying the resource and action. It distinguishes from siblings by detailing the combined sources (deps.dev + bundlephobia) and ecosystem scope.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies when not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already provide safety hints, but description adds meaningful behavioral context: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offset for verification. 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?

A single paragraph with front-loaded purpose, every sentence adds value, and the length is appropriate for the detail provided.

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

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

Even without an output schema, the description explains return format (passages with offsets and scores), cap, and truncation behavior. Complete for a tool of moderate complexity.

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

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

Schema coverage is 100%, and description adds examples for the query parameter and reaffirms limits. This adds marginal value beyond the schema.

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

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

The description uses a specific verb ('search inside') and resource ('fetched record'), and distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded. It clearly states what the tool does.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and pairs with ask_pipeworx_grounded. Does not explicitly state when not to use, but the use case 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?

Disclosures beyond annotations: OAuth requirement, delivery channel constraints (SMS cap, phone verification, webhook auto-disable). Idempotent annotation is present but not repeated; no contradiction. Could add more on idempotency behavior.

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

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

Front-loaded with purpose and return value, then details. Dense but no fluff; slightly long but warranted for complexity. Could be more structured with bullet points.

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?

Highly complete given no output schema: covers all types, delivery options, prerequisites, and constraints. Missing only minor details like error handling or idempotency effects, but overall comprehensive.

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

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

Schema coverage is 100%, but the description enriches each parameter with examples and constraints (e.g., sec_8k item codes, SMS cap, webhook signing). Adds significant value over 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 clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It distinguishes from siblings like list_subscriptions (listing) and unsubscribe (deleting) by focusing on creation.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types and delivery channels. Excludes anonymous/BYO users. However, it does not explicitly mention when not to use this or directly contrast with 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that output includes exact tool calls and argument shapes, which is not in annotations.

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

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

The description is comprehensive but slightly verbose with multiple example phrasings. However, it is well-structured and front-loaded with the key 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 no output schema, the description fully explains what the tool returns (category-bucketed example questions) and how to use it. It positions the tool effectively among many siblings.

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 of the 'topic' parameter. The description adds concrete examples ('finance', 'pharma', etc.) and explains the effect of omitting 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 returns category-bucketed example questions to help users get started. It explicitly says 'use this FIRST when you do not yet know what Pipeworx can do for you', distinguishing it from sibling tools like ask_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?

The description tells when to use it ('first' for onboarding) and lists example topics. It mentions meta-tools as alternatives but does not provide explicit when-not-to-use scenarios.

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 mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds crucial behavioral details: ownership enforcement (only own subscriptions) and that the row is deactivated (not deleted) with historical events preserved. 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 that front-load the action and include all necessary information without redundancy. Every sentence adds value: action, constraint, and side effect.

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

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

For a single-parameter mutation tool with no output schema, the description fully explains the behavior (ownership, deactivation, impact on historical data) and points to related tools (recent_alerts). 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?

The schema is 100% covered with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds context that the id must belong to the caller, slightly enhancing semantic understanding 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 tool is named 'unsubscribe' with title 'Unsubscribe from Alerts', and the description clearly states it cancels a subscription by ID, distinguishing it from subscribe and list_subscriptions. It specifies ownership enforcement and the effect (deactivation, not deletion).

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 tells when to use (to cancel own subscription) and mentions that historical events stay available via recent_alerts, implying an alternative for viewing history. However, it lacks explicit 'when not to use' or other alternatives for cancellation (e.g., administrative cancellation).

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

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

The description goes far beyond the annotations by explaining the two-path routing (SEC EDGAR fast path vs. grounded pipeline), the exact verdict types returned, and the distinction between 'could_not_verify' and 'unsupported.' This adds crucial behavioral context that annotations cannot convey, especially the warning that 'could_not_verify' is not evidence for or against the claim.

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

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

The description is longer than the calibration ideal but is well-structured and front-loaded with examples. Every sentence adds value, covering usage, routing, return values, and important error semantics. The 'Replaces 4–6 sequential calls' note adds useful context, though the description could be tightened without losing key information.

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

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

Given the complexity of the tool and the absence of an output schema, the description is exceptionally complete. It fully explains the verdict vocabulary, the citation mechanism, the meaning of each failure mode, and the fallback routing. This provides the agent with everything needed to correctly interpret and use the tool's results.

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

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

The input schema already provides 100% coverage with detailed descriptions for both 'claim' and 'tolerance_pct'. The tool description does not add parameter-specific guidance beyond what the schema offers, so the baseline 3 applies. The mention of 'exact percent-delta math' is more about the tool's internal logic than parameter usage.

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

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

The description clearly states the tool's function: verifying natural-language factual claims against authoritative sources. It provides specific example intents ('fact check', 'verify the claim that...') and distinguishes this from general Q&A tools by emphasizing claim verification with structured verdicts. The scope is precise (company-financial vs. other claims), making it distinct 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear when-to-use guidance. It also details the routing logic for different claim types, but does not explicitly name alternative tools or exclusion cases, so it lacks the explicit alternative/contrast of a 5.

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