Clevelandart

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds that it scores visibility per model, returns raw responses, and notes cost implications (BYO key for Anthropic). It does not contradict annotations.

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

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

The description is a single, focused paragraph that immediately states the core action. It is concise with no unnecessary words, and the key information is front-loaded.

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

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

Despite lacking an output schema, the description explains the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view'. It covers all parameters and use cases, making it 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%, so parameters are well-described in the schema. The description reinforces parameter meanings (e.g., 'entity' as the thing to ask about, '_apiKey' for Anthropic) but does not add significant new semantics.

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

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

The description clearly states the tool probes LLMs for entity awareness and scores visibility (0-100). It specifies the verb 'probe', the resource 'LLMs', and the output: per-model scores. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on multi-model scoring and mentions 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 context for when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It mentions default model and optional Anthropic key. However, it does not explicitly state when not to use it or compare to alternatives like 'ask_pipeworx'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: routes to thousands of tools, returns pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradictions.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and then organized into purpose, examples, and alternatives. Some repetition exists around when to use it, but the length is justified for a central default 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?

There is no output schema, but the description explicitly states the return type (structured answer with stable citation URIs) and covers scope, limitations, and alternatives. It is complete enough for an agent to decide when and how to invoke this tool, especially with rich annotations available.

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

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

Schema description coverage is 100%, with the 'question' parameter and multiple aliases thoroughly documented in the schema. The description does not add parameter-specific formatting or constraints, so the baseline of 3 applies since the schema already carries the weight.

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 is a routing/answering tool for factual questions, returning structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing when to step up to each.

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 usage guidance: prefer over web search, start here for most questions, and use alternatives only when specific needs arise (hallucination-resistance, multi-part broad research). Names concrete trigger phrases and example queries.

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 context beyond these: the live candidate routing improvements, the current inactive state (retired 2026-07-26), and the reassurance that it is a full working router, not a fallback. This clarifies the experimental behavior without contradicting annotations.

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

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

The description is four sentences, front-loaded with the core identity ('Beta version of ask_pipeworx'). Each sentence adds information: identity, current state, usage, and reassurance. No redundant wording, though slightly longer than strictly necessary.

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 states 'same response shape' as ask_pipeworx, giving the agent a reliable reference for expected output. It covers the beta status, routing behavior, and usage context. Rich annotations compensate for missing output details. Slightly incomplete because it doesn't explicitly describe the response format itself, but referencing the stable tool suffices.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for a natural language question. The description only adds 'same arguments' as a reference to ask_pipeworx, which is minimal. Since the schema already fully explains parameters, a baseline score of 3 is appropriate.

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

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

The description clearly identifies this tool as 'Beta version of ask_pipeworx: identical universal router' with the same 5,529 tools and response shape. It distinguishes itself from sibling ask_pipeworx by being the experimental edge variant, so an agent knows exactly what it does and how it differs.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes results are compared against the stable router, implying this is for testing/experimentation. However, it does not explicitly say when not to use it (e.g., for production), leaving a small gap.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), it discloses the refusal mechanism with enumeration of refusal reasons, the evidence verbatim quote, the extra LLM call cost, and the constraint that it only extracts from tool result content. These additions are meaningful and align with the annotations—no contradiction.

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

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

The description is moderately sized but every sentence adds critical information: purpose, mechanism, return/refusal format, use case, cost, and alternative. The refusal-reason enumeration is long but necessary since there is no output schema. Slightly dense but well-structured.

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

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

For a complex tool with no output schema, the description fully covers the return object, refusal reasons, use cases, and cost tradeoffs. It also references the sibling tool for casual use, making the context complete for an agent to decide and invoke correctly.

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

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

The input schema already covers all 6 parameters (all aliases for question) with 100% description coverage. The parameter semantics are fully provided by the schema, and the description adds no param-specific detail beyond the natural language question context. Baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly explains it extracts answers using ONLY the tool result content. It clearly distinguishes itself from sibling ask_pipeworx by positioning as the grounded counterpart. The verb+resource is specific: it answers questions with evidence and refusal handling.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and directly contrasts with 'prefer ask_pipeworx for casual lookups.' Names the alternative tool and gives a clear decision rule based on stakes and cost.

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 extensive behavioral context beyond annotations: it details fan-out logic, response shapes (market, analysis, evidence), resolver contract (confidence levels, suggestions), safety mechanisms (low-confidence suppression, closed market handling), and resolution-rule risk. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which are not contradicted.

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

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

The description is very long and detailed, which provides thorough information but at the cost of conciseness. It is well-structured with labeled sections, but the verbosity may overwhelm an AI agent scanning for key facts.

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 comprehensively explains all response fields (market, analysis, evidence, resolver contract, parent_event, news fields, safety guards, resolution rules). It covers edge cases (closed markets, wide spreads, rate limits) and provides actionable guidance.

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 covers all 3 parameters with descriptions and examples. The description further clarifies parameter semantics (e.g., market can be slug/URL/text, depth enum behavior, include_raw impact on response size), adding moderate value beyond the schema.

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

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

The description clearly states the verb ('Research') and resource ('a Polymarket bet') with specific actions (pulling Pipeworx data, resolving, classifying, fanning out). It distinguishes from siblings by being tailored to Polymarket bet research, while siblings like ask_pipeworx are for general Q&A.

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 ('should I bet on X', etc.), providing clear context for when to invoke. However, it does not explicitly mention when not to use this tool versus alternatives like polymarket_edges.

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. Description adds details: pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling, FAERS data for drugs, sorted results, citation URIs. 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 a single dense paragraph that packs a lot of information efficiently. It could be slightly more structured for scanning, but every sentence adds value and it is appropriately sized.

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 explains return format (paired data + citation URIs), sorting behavior, and handles edge cases (off-calendar fiscal years). All relevant aspects are covered for a 2-parameter 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%, but description adds meaning beyond enum values: explains that 'values' should be tickers/CIKs for companies or drug names, and provides examples. This clarifies parameter semantics effectively.

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

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

Description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies resources (companies or drugs). It distinguishes from sequential lookups and includes trigger phrases that help an agent recognize when to use this tool.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also includes example queries that indicate context of 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 already declare readOnly, openWorld, idempotent, and non-destructive. The description adds return fields and scope (CMA collection), which is useful but not rich behavioral detail like pagination or matching semantics. 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 three sentences, front-loaded with purpose and returns. The third sentence slightly repeats earlier points, but overall it is efficient and every sentence adds value.

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

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

Given the output schema and rich annotations, the description adequately covers purpose, return fields, and search semantics. Minor gap: the example with 'abstract' suggests query may not always be a name, but the description only mentions name matching, creating slight ambiguity.

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 description explicitly says 'by name', giving meaning to the query parameter which lacks a schema description. The limit parameter is already described in the schema. Thus the description compensates for the 50% schema coverage and clarifies the key 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 clearly states it searches creator records by name, returns specific fields (id, name, role, dates, nationality), and answers which artists match a name. This distinguishes it from sibling tools like get_artwork or exhibitions, which focus on different resources.

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

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

The description provides clear context: it is for searching creator/artist records in the CMA collection by name. It does not explicitly exclude alternatives or name sibling tools, but the context is unambiguous enough that an agent would know when 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context beyond these: the facet decomposition and parallelism, gap recovery at different depth levels, contradictions[] detection, citation_uri fetchability, semantic excerpting of large records, expected latency (15-60s or up to 90s), and the guarantee that it never invents answers. This exceeds what annotations alone convey.

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

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

The description is long but every sentence carries essential information: account requirements, alternatives, mechanism, output format, latency, and caveats. It is logically sequenced (account → what it is → when to use → depth behavior → output details → timing) and avoids filler. It could be improved with bullet points or shorter paragraphs, but it is not redundant or wasteful.

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

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

There is no output schema, so the description carries the burden of explaining return values and behaviors. It covers the findings packet (verbatim evidence + confidence + source + fetched_at + citation), gaps[], contradictions[], hop field, citation_uri resolvability, and edge cases like current-news topics. It also explains account tiers and time expectations. For a tool with two parameters and high complexity, this is a complete and self-sufficient description.

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

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

The input schema already describes both parameters (question and depth) with 100% coverage, giving a baseline of 3. The description adds meaningful semantics by elaborating on each depth value: 'quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop... plus a contradictions[] scan)', and 'thorough=8 (paid; adds a full iterative hop...)'. It also clarifies that the question can be broad/multi-part, reinforcing the decomposition purpose. This extra context justifies a score above baseline.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains it 'Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL'. It uses a specific verb (research), names the resource (structured data sources), and explicitly distinguishes itself from the sibling tool 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 provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and contrasts with alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains exclusion conditions and when deep_research may return empty gaps.

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, idempotentHint=true, destructiveHint=false. Description adds that the tool returns top-N tools with full schemas and curated examples, ready to call directly without a second lookup. No contradiction and no additional behavioral concerns need flagging.

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 front-loaded with a clear purpose statement and includes examples and output details in 4 sentences. Each sentence earns its place. Minor redundancy in mentioning aliases (already documented in schema) but does not significantly detract from conciseness.

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

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

The tool has 6 parameters (mostly aliases) and no output schema. Description covers input format (natural language query), output format (top-N tools with names, descriptions, full input schemas, curated examples), and usage context. All necessary information for an agent to correctly invoke the tool is provided.

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?

Input schema has 100% description coverage for all 6 parameters, including aliases and limit. Description does not add meaning beyond what the schema provides; it merely restates the alias pattern. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

Description uses specific verb 'Find tools by describing', lists covered domains (SEC filings, FDA drugs, etc.), and explicitly states it returns top-N relevant tools with schemas. It distinguishes from siblings by instructing to call this FIRST when exploring options, clearly differentiating its discovery purpose from other tools that perform specific tasks.

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 usage context: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by domain examples. Also includes guidance to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Does not describe when not to use, but the context is clear enough for an agent to decide.

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, open-world, idempotent, non-destructive. The description adds specifics about fan-out across SEC, XBRL, USPTO, news, GLEIF, and what fields are returned, plus the patents soft-fail 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?

Despite being a single paragraph, it is front-loaded with example queries and includes all necessary details without redundancy. Could be slightly more structured but is clear.

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

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

Since there is no output schema, the description fully explains the return fields (cik, company_name, filings with URIs, fundamentals, patents with caveat, news, LEI). Covers all essential aspects for the agent.

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

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

Schema coverage is 100%, but description adds context: value can be ticker or CIK, names not supported; type is only company. Adds meaning beyond schema.

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

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

The description clearly states it provides a full cross-source profile of a US public company in one parallel call, with example queries and explicit distinction from chaining single-source lookups. It differentiates from siblings like resolve_entity.

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

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

Explicitly says to prefer this over chaining for holistic views, and advises using resolve_entity first if only a name is available. Also notes limitations (patents soft-fail) and accepted inputs.

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

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

The description adds behavioral details beyond the annotations: it specifies the return fields (CMA id, title, opening/closing dates, venue) and the scope of coverage ('shows mounted at and organized by the museum'). This complements the readOnlyHint and idempotentHint 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 three sentences, front-loaded with the core purpose, and each sentence adds value: what it does, what it returns, and what question it answers. No redundant or filler content.

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

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

Given the simple 2-parameter schema, comprehensive annotations, and presence of an output schema, the description adequately covers the tool's purpose, scope, and return format. The lack of pagination or sorting details is acceptable because the schema and output schema handle such specifics.

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?

Only the 'limit' parameter has schema description; 'query' lacks one. The description compensates by explicitly stating the search is by 'title keyword', clarifying the meaning of 'query'. With 50% schema coverage, this partial compensation is sufficient, though not exhaustive.

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 searches the Cleveland Museum of Art's exhibition history by title keyword, and specifies the exact question it answers ('whether the Cleveland Museum of Art has shown an exhibition on a subject, and when it ran'). This distinguishes it from siblings like search or get_artwork by narrowing the scope to exhibitions and the museum.

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

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

The description provides clear context for when to use the tool: searching exhibition history at a specific museum by keyword. It does not explicitly name alternative tools or exclusionary conditions, but the scope is well-defined enough that an agent can infer appropriate use cases. No explicit 'when not to use' guidance is 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 convey destructiveHint=true and idempotentHint=true. The description adds minimal context beyond stating it deletes a memory, which is consistent. No contradiction, but limited added value.

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

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

The description is extremely concise with two sentences—one for purpose and one for usage guidance. No wasted words, efficient and clear.

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, no output schema, and adequate annotations, the description covers the purpose, usage context, and relationship to siblings completely.

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 the parameter 'key' described as 'Memory key to delete'. The description does not add additional semantics beyond what the schema already provides, so baseline score 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 action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall', making its purpose unambiguous.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, clearing sensitive data. Also references pairing with remember and recall. Lacks explicit when-not-to-use, but the positive guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds concrete behavior: fetches page, extracts content, emits standard markdown. No contradictions. Provides moderate additional 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 with no waste. First sentence front-loads purpose and output format; second sentence lists use cases. Efficient and well-structured.

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

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

Despite no output schema, description explains return format as a text blob. Two parameters with full schema coverage, no nested objects. Complete enough for the tool's 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 descriptions are already in the schema. Description only adds implicit context (e.g., default/max for max_links is already in schema). No extra meaning beyond what schema provides; baseline score of 3 is appropriate.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, explains the process, and lists specific use cases. It uniquely describes its function, distinguishing it from sibling tools like scan_competitor_ai_presence.

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 three explicit use cases (client indexing, own project, competitor auditing) but does not mention when not to use or alternatives. Clear context, no exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds minimal behavioral context beyond the identifier format, but does not contradict annotations.

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

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

Extremely concise single sentence that front-loads the key information. No wasted words.

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

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

For a simple lookup tool with rich annotations and output schema, the description is complete. It covers the essential usage pattern.

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 examples. The description adds minor clarification on identifier formats, but does not significantly extend beyond what the schema provides.

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

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

The description clearly states the tool retrieves a single artwork using an identifier (accession number or numeric id). It is specific and distinguishes from sibling tools like search or entity_profile.

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

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

The description implies usage when a specific artwork identifier is known, but does not explicitly state when to use or avoid this tool vs alternatives. No exclusions or 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, non-destructive read. The description adds behavioral context by specifying that only active subscriptions are listed by default and listing the exact return fields, which is helpful but not essential given the annotations.

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

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

The description consists of two sentences that are front-loaded with the core functionality and return fields. It is concise and every sentence provides value.

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

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

Given the tool's simplicity (one optional parameter, excellent annotations, no output schema needed because return fields are listed), the description is complete. It covers purpose, return fields, and usage hints without leaving gaps.

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

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

Schema coverage is 100% (one boolean parameter with description). The description does not add any additional semantic information about the 'include_inactive' parameter beyond what the schema already provides. Baseline is 3 due to 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 states it lists the caller's active subscriptions and enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides context on when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It clearly recommends using this before adding a subscription or to find an id for unsubscription, though it doesn't explicitly mention when not to use it.

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

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

The description discloses rate limiting ('5 per identifier per day'), free/quota behavior, the claim_token workflow, and that the team reads digests daily. These behaviors go well beyond the annotations, which only say the operation is not read-only/idempotent/destructive. No contradiction 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 lengthy but dense, with every sentence serving a purpose: purpose, scope limits, token workflow, rate limits, and quota clarification. It is front-loaded with purpose and usage. It loses one point for being slightly sprawling, but it remains highly informative.

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 four parameters, nested objects, and no output schema, the description carries heavy responsibility. It fully compensates by explaining the return token, rate limits, pairing scope, and what should/shouldn't be included. It is complete for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning beyond the schema: it explains how to use claim_token later to read status, instructs users not to paste end-user prompts, and clarifies the 'other' type via the enum descriptions. This elevates the contribution.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx or search by framing it as a feedback/reporting channel for Pipeworx tools specifically.

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

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

Explicit when-to-use guidance is provided for bug, feature/data_gap, and praise cases. It also gives a clear exclusion: only for tools served by this Pipeworx connection, and tells users to file elsewhere for other MCP servers. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII), which are valuable 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?

Description is three sentences plus a bullet list, all front-loaded. Every sentence adds information—no redundancy or filler 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 read-only analytics tool, the description covers its function, parameters, caching, and privacy. Lacks output schema details (e.g., structure of top tools/packs), but is still adequate given 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 covers 100% with enum and description. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the parameter's meaning.

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

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

The description states it returns 'top tools, top packs, and total call volume over a recent window,' using specific verb–resource mapping. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on trending analytics rather than direct Q&A or general discovery.

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

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

Explicitly lists three use cases (hot data sources, canonical tool confirmation, alignment check). While no 'when not to use' is given, the clarity of use cases combined with sibling context provides adequate 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 indicate read-only, idempotent, and non-destructive behavior. The description exceeds this by detailing behavioral traits such as partition checks, semantic anchor for similarity, partition filters, fill check with realizable edge, and the response structure. 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 thorough but slightly verbose. It is well-structured, starting with the main purpose and then detailing each mode. While every sentence adds value, it could be trimmed slightly without losing information. Front-loaded with essential information.

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

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

Despite no output schema, the description thoroughly explains the response fields: opportunities array, partition_check object, fill_check details. It also references a sibling tool for custom sizing (polymarket_fill_risk). For a complex arbitrage detection tool, the description is complete and actionable.

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

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

Schema description coverage is 100%, with both parameters described. The description adds significant meaning beyond the schema, explaining the difference between 'event' (single-event mode) and 'topic' (cross-event mode), and provides examples of valid inputs. It also describes how each mode works and what to expect.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges by specifying its unique detection methods. The verb 'find' and resource 'arbitrage opportunities' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets and explains the differences. However, it does not compare this tool to siblings like polymarket_edges, which could help agents choose between them.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive behavioral context: details on three model families, diagnostics, caching, and what segments exist. 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 long and dense with technical details (e.g., Greek letters, specific thresholds). While front-loaded with purpose, it could be more concise. Every sentence adds value but the volume is high.

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, 9 parameters, no output schema, and rich annotations, the description is very complete. It covers what each segment returns, diagnostics, caching behavior, and edge cases like Fed bets. Provides all needed context for optimal use.

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

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

Schema coverage is 100%, so baseline 3. The description explains high-level knobs like 'tradeable-edge filters' and adds context for parameters like min_partition_leg_kelly that goes beyond schema descriptions. However, it doesn't systematically cover each parameter.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan', 'return') and resource ('Polymarket markets'), and distinguishes from siblings like polymarket_arbitrage by focusing on disagreement with external data.

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 it's built for 'what should I bet on today' and helps agents discover without paging hundreds of markets. It mentions knobs and filters but lacks explicit comparisons to sibling tools 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 indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context: 60-day snapshot TTL, snapshot dates depend on cache-miss, response structure (tracked, expired, snapshot_dates), edge_pp_net sign convention, and decay computation. No contradictions.

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

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

Description is front-loaded with purpose, then structured response details and limitations. Every sentence adds value, but some implementation details ('snapshots are written when polymarket_edges runs on a cache-miss') could be condensed without loss.

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

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

With no output schema, description thoroughly explains return values (tracked, expired, snapshot_dates) and limitations (TTL, decay computation). All aspects are covered for effective use.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal extra: for 'days' it mentions max 30 (schema says clamp 2-30), for 'window' it lists examples matching schema. Does not significantly enhance 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?

Description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It specifies the resource (edges from polymarket_edges snapshots) and distinguishes from sibling polymarket_edges by focusing on historical time-series rather than current snapshot.

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

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

Description provides context for when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades'. It implies usage for historical persistence analysis but does not explicitly mention when not to use or compare to alternatives like polymarket_edges or polymarket_arbitrage.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent with a read-only check. Description adds rich behavioral context: warns about partial basket fills converting arb into unhedged directional position (dominant loss mode), details output fields like forced_directional_risk. 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?

Description is dense and informative, front-loaded with main purpose. However, it is long and could be better structured with clearer paragraph separation for modes. Every sentence earns its place, but a slight loss for length.

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

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

Given no output schema, the description provides comprehensive return field details for both modes, including edge cases (thin_legs, forced_directional_risk) and explains the 'verdict' field. It fully covers the tool's behavior and usage context.

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

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

Schema coverage is 100%, but description adds significant meaning beyond schema: explains size_usd interpretation for single vs basket, side defaults and auto-detection, event for basket mode, market for single mode. Also documents output structure in detail, compensating for missing output 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 checks realizable vs theoretical edge against live order book depth. It distinguishes single-market and basket modes with specific verbs ('walks the ladder', 'returns top_of_book, vwap_fill_price') and is different from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills cause directional risk. Clear context on when to use and what alternatives (polymarket_arbitrage, polymarket_edges) exist.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent; description adds detailed context on compatibility_warning triggers, temporal alignment, leg counters, and safety fields beyond 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?

Description is well-structured with sections and front-loaded main purpose, but slightly verbose with extensive details on compatibility_warning and counters; could be trimmed without losing clarity.

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

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

No output schema, but description thoroughly explains response structure (leg-by-leg prices, matched spread, safety fields) and covers complexity of cross-venue comparisons, making it self-contained.

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

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

Schema covers all parameters with descriptions; description adds value by explaining topic shortcuts, how explicit overrides work, and response structure, but schema already provides core meaning.

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 computes cross-venue spread between Kalshi and Polymarket, differentiates two modes (topic shortcuts and explicit tickers), and distinguishes from sibling tools like polymarket_arbitrage by focusing on this specific use case.

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 explains when to use topic vs explicit mode, notes that pre-mapped topics often return compatibility_warning, and clarifies temporal alignment conditions that make spreads meaningless.

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

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

Annotations already cover read-only, idempotent, non-destructive nature. Description adds scoping by identifier and behavior of omitting key to list all, which is valuable context.

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

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

Three concise sentences that are front-loaded with main action, then provide examples and relationship to siblings. No wasted words.

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

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

Given one optional parameter, no output schema, and annotations covering safety, the description fully explains behavior, scoping, and sibling context.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning by explaining the two modes (retrieve vs list) and the origin of saved values ('via remember').

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 retrieves a saved value or lists all keys. Mentions pairing with 'remember' and 'forget' siblings, distinguishing itself.

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

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

Provides explicit use cases (look up ticker, address, notes) and pairs with sibling tools. Lacks explicit when-not-to-use guidance, but usage context is clear.

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

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

The description describes setting mark_read:true to flag events as read, which implies a state change. However, the annotations declare readOnlyHint:true and destructiveHint:false, creating a contradiction. According to guidelines, this yields a score of 1.

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

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

The description is four well-structured sentences. The first sentence states the purpose, followed by return fields, filtering options, and special behavior. Every sentence adds essential information without redundancy or verbosity.

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 five optional parameters, no output schema, and use case (polling for alerts), the description covers all key aspects: purpose, return fields, filtering, mark_read effect, and an alternative access endpoint. It lacks explicit mention of pagination or error handling but is sufficiently complete for this context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying return fields (source, citation_uri, raw event payload), giving an example filter value ('sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the effect of 'mark_read'. This exceeds baseline.

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

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

The description uses specific verbs ('Pull fired events from your subscription feed') and clearly states the resource (recent alerts) and the action. It distinguishes this tool from siblings like 'list_subscriptions' by focusing on 'recent alerts' specific to subscription feed events.

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

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

The description provides clear usage context: it's for pulling the most recent alerts from a subscription feed, with optional filtering by type and since timestamp. It mentions mark_read behavior and confirms polling works. However, it does not explicitly state when not to use it or name alternatives among siblings.

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?

Discloses multi-source fan-out (SEC, GDELT→GNews fallback, USPTO soft-fail), return structure (changes[] grouped by source, total_changes, citation URIs), and rate-limiting fallback. Complements annotations (readOnly, idempotent) with operational details.

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

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

Single paragraph packs examples, behavior, parameter details, and alternative tool. Slightly dense but well-organized with front-loaded examples.

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 adequately explains return shape. Covers all parameters, fallbacks, and soft-fail scenarios. No gaps for agent to invoke correctly.

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

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

Adds significant value beyond schema: 'since' parameter explained with examples ('2026-04-01', '7d', '30d') and recommendation '30d' or '1m'. 'value' clarifies ticker or CIK. 'type' notes only 'company' supported.

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 opens with clear query examples ('What's new with X') and states 'change feed for a company in the last N days...'. It distinguishes from sibling entity_profile for static profiles. Verb and resource are specific.

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 entity_profile instead when you want the static profile', providing clear alternative. Also implies usage for temporal monitoring vs static retrieval.

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

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

Annotations already indicate idempotent and non-destructive behavior. Description adds useful context about key-value pairs being scoped by identifier and session duration (24h for anonymous), which annotations do not cover.

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 concise, well-structured, and front-loaded with purpose, then usage, then behavioral details. Every sentence adds value.

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

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

Completely covers storage behavior, persistence, pairing with other tools, and typical use cases. No output schema exists, but the tool's effect is adequately explained.

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

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

Schema already provides descriptions with examples for both parameters. Description reinforces meaning but adds little new information beyond what is in the input 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 the tool saves data for reuse, gives concrete examples (tickers, addresses, preferences), and distinguishes from sibling tools recall and forget.

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 when to use (discover something worth carrying forward) and mentions alternatives (recall, forget), but does not explicitly state when not to use.

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

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

The description adds behavioral context beyond the annotations: identifiers are labeled with their source, unresolved identifiers are explicitly included under 'unresolved', and enrichment degrades gracefully (e.g., EDGAR IDs still return if GLEIF/OpenFIGI are unavailable). It also reveals the internal cascading of lookups.

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

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

The description is thorough but presented as a single dense paragraph with many nested examples and clauses. While it covers essential points without being overly verbose, a more structured format (e.g., bullet points for supported types) would improve readability. Still, every sentence contributes useful 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 tool's complexity and lack of an output schema, the description thoroughly explains return values, source attribution, unresolved reporting, and fallback behavior. It fully equips an agent to understand what the tool does and what to expect, including potential availability issues.

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 descriptions for both parameters (type and value), including valid examples and formats. The description adds context about what each type returns, but it does not significantly enhance the meaning of the parameters themselves 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 resolves user-spoken names to canonical identifiers, uses concrete examples of natural language queries, and specifies supported types (company, drug) with their respective outputs. It differentiates itself from siblings by instructing 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides explicit usage guidance ('Use FIRST whenever you have a name but need an ID') and notes it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use the tool or name specific alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds specific behavioral details: probes each entity, ranks by score, returns confidence and signal density. Does not mention API key requirements or potential latency, but overall adds value beyond annotations.

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

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

Two sentences plus an example. Front-loaded with the main purpose. 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?

With no output schema, the description partially explains the output (ranked list with score, confidence, signal density). It covers the core functionality but doesn't detail error handling or exact output structure. Given the annotations, 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 has 100% coverage, but the description adds that the first entry in entities is treated as the 'subject' for narrative, and that models can be omitted for default. This provides context beyond the schema.

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

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

The verb 'compare' and resource 'AI visibility' are specific and clear. The distinction from sibling ai_visibility_check (single entity) is implied by 'across multiple entities'. The example question reinforces the competitive audit use case.

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?

States it's useful for competitive AI-marketing audits, with a concrete example. Does not explicitly say when not to use or name alternatives, but the context is clear enough for selecting this tool over a single-entity check.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts.

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 somewhat long (4 sentences) but each sentence adds valuable information. Front-loaded with core purpose, then usage, then behavior. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, the description adequately explains return values (summary block, advisories, links, alternatives), timing, and error handling. Covers all necessary context for a composite tool.

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

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

Schema coverage is 100% (both parameters described). Description adds value by mentioning scoped packages accepted and default version behavior, going beyond the schema's basic descriptions.

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

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

The description clearly states a specific verb+resource ('composite check for adding npm package') and distinguishes from siblings by noting NPM-only scope and mentioning alternative tools for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies NPM-only scope and fallback for other ecosystems, providing clear when-to-use and when-not-to-use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the tool's safety is clear. The description adds that filters are optional, which is useful but not essential behavioral context.

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

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

The description is a single short sentence that front-loads the core action and lists filters. Every word is meaningful with no redundancy.

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

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

While there is an output schema, the description omits important parameters like 'query' and pagination (skip, limit). It covers only a subset of filters, leaving out core search functionality. More detail would improve completeness.

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

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

Schema description coverage is 86%, so the schema already documents parameters well. The description only lists some filters (type, artist, has_image, cc0) without adding new meaning 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 verb 'Search' and the resource 'artworks', listing optional filters. It distinguishes its purpose from sibling tools like 'search_within' by focusing on artworks.

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

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

The description mentions optional filters but provides no guidance on when to use this tool versus alternatives like 'search_within' or other search tools. No exclusions or context 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?

The description goes beyond annotations by detailing the embedding model (BGE-base-en), scoring method (cosine), window size (500-char overlapping), character cap (200K), and truncation behavior. No contradiction with annotations (all safe hints).

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

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

Single, well-structured paragraph with key information front-loaded. Every sentence adds value without redundancy.

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

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

For a simple tool with no output schema, the description covers input constraints, output format (passages with offsets and scores), and practical use case. Pairs well with sibling tool. Complete 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 good descriptions. The description adds extra context (e.g., 'text you already pulled', query examples, max length) that enriches 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 explicitly states 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K body, article). It clearly distinguishes from general search or other tools by specifying it works on text already retrieved.

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 when 'the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded for a workflow. It lacks explicit when-not-to-use statements but provides clear context for appropriate usage.

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

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

Provides extensive behavioral details beyond annotations: requires OAuth account, phone verification for SMS, 10/day cap for SMS, auto-disable webhook after 10 failures, and returns subscription ID. Annotations indicate write, openWorld, idempotent, non-destructive, and the description aligns and enriches these hints.

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

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

Front-loaded with main purpose, but description is lengthy due to comprehensive information. Every sentence adds value, but could be slightly more structured (e.g., bullet points for types). Still effective and well-organized.

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: supported types with examples, parameter format, delivery options, return value, prerequisites (OAuth), and constraints (SMS cap, webhook auto-disable). No output schema, but description explains return. Complete for a tool of this complexity.

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

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

Adds substantial meaning to all parameters: explains enum values with concrete examples, details type-specific params format, and describes delivery channel constraints (phone verification, SMS cap, webhook signing). Schema coverage is 100%, but description provides actionable examples and constraints.

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 describes creating a proactive monitoring subscription to a live-data event stream, returning a subscription ID. Distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Specifies usage context (proactive monitoring, requires Pipeworx OAuth account) and lists supported types and delivery channels. Does not explicitly state when not to use it or mention alternatives beyond implied pull tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that it returns question examples with tool+argument shapes and serves as an onboarding entry point, providing 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?

The description is moderately verbose but each sentence adds value; it lists example questions first, then what is returned, then usage instructions. Could be slightly more concise but remains clear.

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 input schema (no output schema, one optional param), the description is complete: it explains purpose, usage, scenarios, and even lists the categories and mentions meta-tools.

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 description explains that the optional `topic` parameter focuses on a specific area (e.g., finance, pharma) and that omitting it gives a cross-category spread, adding meaning beyond the schema's description of 'optional focus area'.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions, distinguishing it from sibling tools by specifying it should be used first to learn what Pipeworx can do.

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 this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments or with a `topic` parameter to focus, indicating when to use and how.

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?

Discloses that the row is deactivated, not deleted, and historical events remain. Adds behavioral nuance beyond annotations (destructiveHint: false aligns). 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?

Two efficient sentences covering all key points with no fluff. Slightly front-loaded.

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

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

For a single-parameter tool with annotations, the description covers purpose, ownership, and behavioral nuance. Lacks return value details, but no output schema expected.

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 ownership context for the 'id' parameter but otherwise relies on 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?

Explicit verb 'Cancel' plus specific resource 'subscription by id'. Clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear context. No explicit when-not-to-use, but adequate for given complexity.

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

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

Annotations declare readOnly/openWorld/idempotent, but the description adds critical behavior: the distinction between could_not_verify and unsupported, the requirement not to present could_not_verify as evidence, the error structure verification_error, and the two verification pipelines (SEC EDGAR/XBRL vs grounded). 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 long but every section adds value: query examples, usage trigger, pipeline distinction, return values, error semantics, and performance note. It is front-loaded and well-structured; could be trimmed but not at the cost of essential 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?

No output schema, but the description fully compensates by listing the verdict enum, the return value with citation, reasoning, and the caller-facing error semantics. It also explains fallback routing, making it complete for the tool's complexity.

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

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

Schema description coverage is 100% for the two parameters; the description adds no extra detail about claim/tolerance_pct beyond the schema. Baseline 3 applies as the schema does the heavy lifting.

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

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

The description states a clear purpose: natural-language claim verification against authoritative sources, with explicit example query phrasings and a defined set of verdicts. It distinguishes itself from sibling tools by focusing on fact-checking a claim, not general search or research.

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

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

It states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the two internal paths (financial vs other claims). It doesn't explicitly name alternatives or when not to use it, but the trigger is unambiguous.

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