Latam Validate

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

Description adds key behaviors beyond annotations: mentions default model (Workers AI Llama-3.3-70b), optional Anthropic probing with BYO key and direct payment. No contradiction with readOnlyHint/idempotentHint.

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

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

Two concise sentences with front-loaded purpose, key behavior (default model, API key), and return structure. 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?

Describes return format (per-model scores, combined view) despite lack of output schema. Adequate for a moderate-complexity tool with 4 parameters.

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; description adds context like default model for `models`, purpose of `_apiKey` (passed to Anthropic), and role of `context` for disambiguation.

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 specifies a clear action: probe LLMs for knowledge about an entity and score visibility (0-100). It distinguishes itself from sibling tools like `scan_competitor_ai_presence` by focusing on per-model scoring and API key usage.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Could improve by mentioning when not to use (e.g., for deep factual QA), but the listed scenarios are sufficient.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it routes across thousands of tools, fills arguments automatically, and returns pipeworx:// citation URIs. It doesn't detail latency or citation formatting, but the annotation coverage lowers the burden and the added behavioral context is meaningful.

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

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

The description is front-loaded with the most important routing guidance, then builds logically through scope, usage triggers, examples, and sibling-tool alternatives. Despite covering a broad tool, every sentence contributes meaningful selection or invocation information with no filler.

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

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

For a tool with only one required parameter, rich annotations, and no output schema, the description provides a complete operational picture: what it covers, how it behaves, when to prefer it, when to switch to alternatives, and what kind of answer to expect. The examples further ground the expected usage.

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

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

The input schema documents all six parameters at 100% coverage, with five clearly marked as aliases of 'question', so the baseline is 3. The description adds useful semantics by explaining that the tool fills arguments itself and by showing acceptable natural-language question patterns through examples.

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

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

The description clearly states what the tool does: it routes a natural-language question to an appropriate internal tool across verified sources, fills arguments, and returns a structured answer with citations. It also distinguishes itself from web search and explicitly names sibling alternatives like ask_pipeworx_grounded and deep_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 gives explicit preference instructions ('PREFER OVER WEB SEARCH'), trigger phrases ('what is', 'look up', 'find', 'get the latest'), concrete examples, and conditional alternatives for related tools. This gives an agent clear criteria for selecting this tool versus its 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?

Annotations already convey read-only, idempotent, non-destructive behavior; the description adds meaningful context about the experimental nature, candidate lifecycle, and that it is a full working router rather than a fallback. This goes beyond the structured 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 front-loaded with the core identity, current state, and usage guidance. Some details like the exact retirement date and 'falls back to nothing' phrasing are useful but could be tightened without losing meaning.

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

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

For a complex universal router, the description adequately covers current behavior, parity with ask_pipeworx, and the same response shape, so an agent can proceed. A direct statement of what the response contains would improve completeness, but delegation to ask_pipeworx is reasonable given the stable sibling exists.

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 aliases (q, text, input, query, prompt) are already documented. The description only says the tool takes 'the same arguments' as ask_pipeworx, which adds no new parameter-level meaning beyond what the schema provides.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' and an 'identical universal router', so an agent can tell it routes questions to the same 5,798 tools as ask_pipeworx. It distinguishes itself from the stable router by calling out the experimental edge, but it does not explicitly contrast itself with the sibling ask_pipeworx_grounded.

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

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

The description gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes it 'currently matches ask_pipeworx exactly' because no candidate is active. It does not spell out when not to use this variant or how it differs from ask_pipeworx_grounded, but the primary routing decision 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?

Beyond readOnly/openWorld already in annotations, the description reveals substantive behavior: same routing as ask_pipeworx, extraction constrained to the tool result, explicit success and refusal payloads, refusal reason enum, and the extra LLM call cost. This gives agents a realistic model of failure and cost.

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

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

Every sentence earns its place: purpose, routing behavior, return contract, refusal contract, usage context, and cost tradeoff. The most important distinction (hallucination-resistant, high-stakes) is front-loaded, and no filler is present.

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

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

With no output schema, the description fully specifies the success return shape, the refusal shape, and every possible refusal_reason value. It also covers the cost delta and sibling routing, making the tool self-sufficient for correct invocation.

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

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

Schema coverage is 100%, with every parameter documented as an alias for question, so the description does not need to repeat parameter details. It also adds no new parameter-level guidance, so the high-coverage baseline of 3 is appropriate.

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

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

The description names a specific function: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from tool results. It also contrasts itself with ask_pipeworx, so an agent can distinguish this grounded mode from the standard sibling.

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

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

Explicitly states when to use it: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples like financial verdicts and legal claims. It also gives the when-not-to-use case by preferring the cheaper ask_pipeworx for casual lookups.

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

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

Annotations (readOnly, idempotent, non-destructive) are supplemented with extensive behavioral details: low-confidence short-circuit, closed/dead market handling, wide-spread warning, resolution-rule risk, resolver contract, parent event extractor, news fallback fields, and blocking behavior. 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 lengthy (multiple paragraphs, dense with examples and edge cases). While well-organized with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), it could be more concise. The level of detail is appropriate for the tool's complexity, but it sacrifices brevity.

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 (classifier, fan-out, resolver, parent events, news fallback, safety, cancellation rules) and no output schema, the description is remarkably complete. It covers response structure, edge cases, error handling, and practical caveats (e.g., resolution-risk). An agent has sufficient information to use the tool correctly.

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

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

Schema covers 100% of parameters with good descriptions. The description adds value by explaining the impact of `include_raw` (response size), the meaning of `depth` with quick vs thorough, and provides examples for the `market` parameter (slug, URL, question text). This extra context justifies a score above baseline 3.

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

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

The first sentence states the tool's purpose precisely: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains input types (slug, URL, question text) and the overall process (resolve, classify, fan-out, return evidence+comparison). This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides fan-out examples for various bet categories, giving clear context. Does not explicitly mention when not to use or compare with siblings, but the usage guidance is strong overall.

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 readOnlyHint, idempotentHint, destructiveHint=false. Description adds that data comes from central-bank registry but no additional behavioral details (rate limits, freshness). 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?

Two sentences: first states purpose with fields, second gives usage example. No wasted words, front-loaded with key information.

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

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

For a simple lookup tool with 3 optional parameters and no output schema, description lists returned fields (COMPE, ISPB, name) and gives examples. Could mention ISPB definition or default limit, but adequate.

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

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

Schema coverage is 100%, so baseline is 3. Description adds real-world examples (code 1 → Banco do Brasil) and explains usage pattern (optional filter by name/code), providing extra value beyond schema.

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

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

Description clearly states it lists Brazilian banks with specific fields (COMPE, ISPB, name) and gives concrete examples (code 1 → Banco do Brasil). It distinguishes from sibling tools (no other bank lookup exists).

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 to resolve a bank code from a boleto or PIX/TED transfer'. Provides clear context for when to use. No explicit when-not or alternatives, but siblings don't overlap, so it's adequate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds value by specifying the returned data (street, neighborhood, city, state, coordinates) and giving an example.

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 sentence with an example, highly concise, and front-loaded with the main purpose.

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

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

For a simple read-only lookup with one parameter and no output schema, the description adequately explains input and output. Minor gap: does not mention error handling for invalid CEPs.

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 includes a clear example and format. The description repeats the example but adds no new information beyond the schema.

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

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

The description clearly states the tool's purpose: lookup a Brazilian CEP and return address details. It includes a specific example and distinguishes it from sibling tools like brasil_banks.

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?

While no explicit when-to-use guidance, the straightforward description and example imply usage for CEP lookup. No obvious alternatives among siblings, so no exclusion is needed.

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, etc.), the description adds significant behavioral context: for companies it pulls real-time data from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drugs it pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also notes results are sorted by primary metric and returns citation URIs. No contradictions with annotations.

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

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

At ~120 words, the description is information-dense and front-loads common query patterns. Uses bold emphasis and examples effectively. While efficient, it could be slightly more concise without losing meaning, but overall it earns its length.

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

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

Given the tool's complexity (comparison of 2-5 entities, two types with different data) and the absence of an output schema, the description covers intended use, alternative to sequential lookups, data sources, sorting, and return format (paired data + citation URIs). It is complete and leaves no major 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%, so baseline is 3. The description adds value by explaining the 'type' parameter's effect (company vs drug) and providing concrete examples for 'values' (tickers/CIKs for companies, drug names for drugs). It also mentions edge cases like off-calendar fiscal years, enhancing understanding beyond the schema's enum and string 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 starts with common query patterns and clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It specifies what each entity type retrieves (financial data from SEC for companies, FAERS data for drugs) and highlights that it replaces 8-15 sequential lookups, effectively distinguishing it from sibling tools like entity_profile.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong guidance. It also describes behavior for queries like 'largest/most/biggest' but does not explicitly mention when not to use the tool (e.g., for more than 5 entities). Overall, it offers clear context on 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 already declare the tool safe and read-only, and the description adds substantial behavior beyond that: required auth/plan, structured datasource scope, parallel decomposition, findings packet structure, explicit gaps[] for unanswered facets, no hallucination guarantee, contradiction scans, citation_uri fetchability, semantic excerpting, and expected latency. Nothing contradicts the annotations.

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

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

The description is dense and front-loaded with the account requirement and fallback before the core definition. It is long, but nearly every sentence carries operational value; a small deduction because some depth-mode behavior is already present in the detailed schema description and the prose is heavy with parentheticals.

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

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

With no output schema, the description carries the full burden of explaining return structure. It enumerates findings, evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[], and semantic excerpting, plus latency. An agent has enough to select and invoke the tool correctly without external documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by clarifying that the question parameter is meant for broad/multi-part natural-language research and that single lookups should be routed elsewhere. It also enriches depth semantics with latency behavior and auth/paid-plan implications that go beyond the enum labels.

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

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

The description names a specific verb/resource: grounded multi-source research over Pipeworx's structured data sources, and explicitly disclaims open-web search. It also gives a concrete example question type, which makes the tool's scope immediately recognizable relative to siblings like ask_pipeworx.

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

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

The description explicitly says when to use deep_research ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'). It also provides an auth fallback: if not signed in, use ask_pipeworx because it works on every tier.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This discloses response format and usability beyond annotations. No contradictions.

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

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

The description is a single paragraph but well-structured, starting with the core purpose, then listing applicable domains, then explaining return value. It is not overly verbose for the information conveyed. Some agents might prefer bullet points for clarity, but it remains readable and 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 the tool's complexity (6 parameters, mostly aliases) and the presence of annotations covering safety, the description provides sufficient context: it explains the use case, return format (top-N tools with schemas), and how results are ready to call. No output schema exists, but the description covers the output sufficiently. Examples in the input schema further aid 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 coverage is 100%, so parameters are fully documented. The description mentions that query accepts natural language and lists aliases (task, q, description, search) which are already in the schema. It adds examples but no additional semantic depth. Baseline 3 is appropriate as the description does not significantly augment parameter 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 the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set.' The verb 'discover' and resource 'tools' are precise.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available.' This provides strong guidance. It lacks explicit 'when not to use' but the context makes it clear that if you already know the tool, you wouldn't use this. The sibling list is large, so the tool fills a clear discovery niche.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses source fan-out, the GDELT→GNews fallback, the USPTO sunset soft-fail, the meaning of empty sections via sources_used/sources_failed, and the resolved:false behavior for private companies. This is rich behavioral context that annotations alone could not convey.

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

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

The description is dense but front-loaded with trigger phrases and the usage preference, and nearly every sentence carries useful information. It loses one point for redundancy with the schema—the type/value interchangeability is stated in both places—and for being a long single paragraph that is somewhat heavy to skim.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, resolved fields, recent_filings with URIs, fundamentals, sources_used/sources_failed, and explicit no-data semantics. The edge cases a caller would care about are all covered.

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

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

Although schema coverage is 100%, the description adds meaningful parameter nuance: zero-padded CIK examples, ticker/CIK/name equivalence, SEC EDGAR name resolution, resolved_from/resolved_to, and private-company resolved:false behavior. This substantially exceeds the baseline expected for fully documented schemas.

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 produces a full cross-source profile of a US public company, backed by concrete trigger phrasing like 'brief me on Tesla' and 'company profile for Microsoft'. It distinguishes itself from piecemeal lookups by emphasizing the single parallel call and holistic scope.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving an unambiguous selection rule. It also specifies accepted input forms and explains the private-company failure mode, so an agent knows when the tool can and cannot be used.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description reinforces the destructive nature ('Delete') and adds context about clearing sensitive data, which is helpful but not beyond what annotations provide. No contradictions.

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

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

Two sentences, front-loaded with the action, no wasted words. Every sentence provides value: action, usage context, and companion tools.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, usage triggers, and relationships. Annotations cover the destructive behavior, so no further elaboration needed.

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

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

Schema coverage is 100% for the single parameter 'key', with a clear description 'Memory key to delete'. The description does not add additional parameter details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key ('Delete a previously stored memory by key'). It distinguishes from sibling tools 'remember' and 'recall' by explicitly mentioning pairing and contrasting operations.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests complementary tools ('Pair with remember and recall'), offering clear alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds details about fetching the page, extracting title/description/key links, and outputting markdown format, which provides 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 a single, well-structured paragraph with no wasted words. It front-loads the primary action and efficiently covers purpose and use cases.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully explains the input, process, and output format. No gaps or missing information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds default and max for max_links, but this is marginal additional value. No significant new meaning beyond the schema.

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

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

The description clearly states it generates a llms.txt file for any URL, using a specific verb and resource. It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation for AI indexing.

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 lists explicit use cases (e.g., getting a client's site indexed, drafting for own project, auditing competitors), providing clear context for when to use it. It does not include exclusions or alternatives but is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing return fields (id, type, params, etc.) and usage context. 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 sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

For a simple list tool with one optional parameter, description covers return fields and usage context. No output schema, but fields are listed. Adequate for agent use.

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

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

Schema coverage is 100% for the single boolean parameter. Description does not reiterate parameter details, but schema already covers it. Baseline 3 applies.

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

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

States 'List the caller's active subscriptions' – specific verb and resource. Differentiates from sibling tools like subscribe and unsubscribe by mentioning review before adding more or finding id to cancel.

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 to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for use, though doesn't 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 richly discloses behavioral traits beyond annotations: it reveals rate limiting (5 per identifier per day), that it is free and does not count against tool-call quota, how claims tokens work, that the team reads digests daily, and that filing without an account returns a claim_token. The annotations (readOnlyHint=false, destructiveHint=false) are not contradicted; the description adds valuable operational 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?

Although longer than typical, every sentence serves a distinct purpose: core purpose, use cases, exclusion, claim_token mechanics, rate limits, and cost. The description is front-loaded with the primary action and maintains a logical flow. There is no redundancy or irrelevant filler.

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

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

With no output schema, the description compensates by explaining what happens (returns claim_token, how to check status later, what the team does). It covers both invocation modes, scope, and constraints (rate limit, quota). For a tool with optional parameters and no output schema, this description is exceptionally complete for agent 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?

Schema coverage is 100%, so parameters are already well described. The description adds meaning by giving an example call for claim_token (pipeworx_feedback({claim_token:"pwfb_…"})) and instructing users not to paste the end-user's prompt, which clarifies the expected message content. It also reiterates the 2000-char limit (already in schema) but adds the '1-2 sentences typical' guidance, slightly enhancing schema semantics.

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

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

The description opens with a clear, specific verb phrase ('Tell the Pipeworx team something is broken, missing, or needs to exist') and then enumerates the exact feedback categories (bug, feature, data_gap, praise). It clearly distinguishes this tool from its siblings by framing it as feedback about the Pipeworx tool catalog itself, not as a research or validation 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?

The description explicitly states when to use the tool (wrong/stale data, missing tool, praise) and provides a concrete exclusion: do not report issues for MCP servers outside this Pipeworx connection, with a directive to file those with the respective server. It also clarifies the claim_token flow, making the two usage modes (filing vs. reading a reply) unambiguous.

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, destructiveHint. The description adds valuable context: data origin ('CF analytics-engine'), no PII, data structure ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). There is 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: purpose, use cases, data details. Every sentence adds distinct value, and the most important information (what the tool returns) is front-loaded. No unnecessary words.

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

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

Given low complexity (1 optional param, no output schema, rich annotations), the description covers data source, privacy, caching, use cases, and parameter guidance. It is complete for its scope.

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 single parameter 'window' has full schema coverage (100%) with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' and implies a default of '24h'. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This specific verb+resource combination distinguishes it clearly from siblings like 'discover_tools' or '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 explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case) and mentions caching behavior. While it does not include when-not-to-use or alternatives, the use cases provide clear context for appropriate invocation.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that the tool is analytical (no mutations). It adds extensive behavioral context: the logic of partition_sum checks, similarity anchors, placeholder filters, and the fill check against live CLOB depth. It also explains when results should not be traded (realizable_edge_pp ≤ 0). 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 detailed and well-structured, starting with the main purpose followed by mode-specific guidance, then response format. However, it is fairly long (several paragraphs) and includes technical jargon (Jaccard similarity, CLOB depth, placeholder fraction) that could be streamlined for quicker understanding. Still, 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 tool's complexity (arbitrage detection with multiple modes, similarity checks, response structure with gaps, partition checks, fill checks), the description is remarkably complete. It explains the output fields, edge cases (skipped_low_similarity, placeholders), and when to consider the results actionable. No output schema exists, so the description appropriately covers return values.

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 covers 100% of parameters, but the description adds significant value: it explains that omitting both args triggers a trending scan, provides examples of valid event slugs and topic seeds, and details the internal logic for each mode (e.g., partition_check, Jaccard similarity). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with three distinct modes (trending scan, event-specific, cross-event topic). It is specific about the verb 'find' and the resource 'arbitrage opportunities on Polymarket'. The detailed behavior distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It provides guidance on what arguments to pass (event slug, topic seed) and when not to trade (realizable_edge_pp ≤ 0). It also mentions an alternative tool (polymarket_fill_risk) for custom sizing.

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

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

The description adds extensive behavioral context beyond annotations: caching (1h at KV level), diagnostics output (filter_skips), placeholder-slug filtering, and model details (e.g., lognormal barrier, GDELT news momentum). No contradiction with annotations.

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

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

The description is dense and well-structured with sections and parentheses, but it is somewhat verbose. Every sentence adds value, but it could be slightly trimmed without losing information.

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

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

Given the complexity (9 parameters, no output schema), the description is thorough. It covers the three segments, edge calculation, knobs, diagnostics, and even the Fed market note. The only minor gap is the exact return format, but top-level fields are described.

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

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

Schema coverage is 100%, but the description adds significant extra meaning: explains tradeable-edge knobs, details on min_partition_leg_kelly (why min_kelly doesn't filter partitions), and gives context like slippage assumptions and default values. Schema alone would not convey this depth.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the use case ('what should I bet on today') and distinguishes from sibling tools by focusing on Pipeworx disagreement and opportunity 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?

The description provides explicit guidance on when to use the tool (discovering opportunities without paging hundreds of markets) and explains filter knobs (min_liquidity, max_spread_pp, etc.). It does not explicitly contrast with siblings like 'polymarket_arbitrage' but implies differences through the focus on Pipeworx data.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds beyond that: how data is computed (from daily snapshots, time-series, decay per day), what the response includes (tracked, expired, snapshot_dates), and limitations (snapshot gaps, not intraday). 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 relatively long but each sentence adds value. It is front-loaded with the core question and structured response. A slight reduction in verbosity could improve conciseness, but it is still 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 fully explains the response structure (tracked with time-series, trend, decay; expired with lifespan; snapshot_dates). It covers data source, computation, and limitations. For a read-only tool with two optional parameters, this is comprehensive.

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

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

Schema coverage is 100% with descriptions. The description adds meaning: days lookback default 14, max 30 (clamp 2-30), window specifies snapshot family (24hr, 1wk, 1mo). It explains the purpose of each parameter 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 (answers 'how long has this edge existed and is it shrinking?') and resource (edge persistence and decay telemetry from polymarket_edges snapshots). It distinguishes from sibling tools like polymarket_edges by focusing on time-series and decay rather than current edges.

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

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

The description explicitly states the question the tool answers, implying when to use it (when longevity matters). It contrasts with sibling tools implicitly: fresh vs. old edges are different trades. It also notes limits (60-day TTL, daily closes) that guide usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: walks the ladder, reads CLOB depth, returns fill details and verdict. It warns about thin legs and directional risk, which goes beyond annotations. No contradictions.

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

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

The description is long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the purpose. Every sentence adds value, though some sentences are dense. Could be slightly more concise, but structure aids readability.

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 (two modes, many output fields) and no output schema, the description is remarkably complete. It enumerates return fields for each mode, explains risks (thin legs, directional risk), and provides the 'capture_ratio' and 'clean_notional' details. No output schema needed.

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

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

Schema description coverage is 100% (all 4 properties described). The description adds significant meaning: explains mode-dependent behavior of side and size_usd, gives defaults, and clarifies interpretation differences between single-market and basket. This far exceeds the schema alone.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket) and what each returns. It distinguishes itself from sibling tools like polymarket_arbitrage by explicitly saying to use this before acting on those signals.

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: before acting on polymarket_arbitrage signals or trades above ~$500. It explains consequences of not using (partial fills, directional risk) and states requirements (one of market or event). Alternatives are implied via sibling tool names.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail: compatibility warnings, per-entry flags, temporal_alignment null semantics, skipped-unclassified legs, and the gross-fee limitation. These disclosures go far beyond the structured annotations and directly prevent misinterpretation of results.

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 it is deliberately structured with bolded mode labels, uppercase safety-field names, and code lists. It front-loads the core purpose and then provides dense, decision-relevant caveats. For a tool with this many edge cases and no output schema, the length is justified and every section addresses a distinct operational concern.

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 three optional parameters and no output schema, the description is unusually complete: it covers the response structure, safety fields, compatibility codes, per-entry flags, temporal alignment semantics, fee treatment, skipped counters, and the limitation that pre-mapped topics are rarely tradeable. An agent has enough information to invoke both modes and correctly interpret returned pairs.

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

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

The input schema already documents all three optional parameters with 100% coverage, so the baseline is a 3. The description adds meaningful context by explaining that the two explicit parameters override the topic-mapped side and that both modes run the identical token-overlap matcher with the same disclosures, which is not fully evident from the schema alone.

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

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

The opening sentence names a specific operation and scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The description then explains two concrete modes and the response content. It is conceptually distinct from single-venue siblings like polymarket_edges, but it never explicitly names an alternative, so the differentiation is implicit rather than explicit.

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

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

The description gives clear usage context: use `topic` mode for the 10 pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, with the important caveat that both modes run the same matcher. It also warns that pre-mapped topics are not automatically tradeable. It does not explicitly list sibling alternatives or state when to prefer another tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful context about scoping and pairing, but doesn't provide additional behavioral details beyond what annotations 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?

Three sentences with no wasted words. The primary action is front-loaded, 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 single parameter with full schema coverage and no output schema, the description provides sufficient context: purpose, usage, scoping, and relationship to sibling 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?

Schema coverage is 100% with a clear description for the single parameter. The description repeats the parameter's behavior (omit to list all keys) without adding new semantic meaning beyond the schema.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via remember). It explicitly distinguishes from siblings by naming 'remember' and 'forget' as paired tools.

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

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

States when to use: to look up context stored earlier, with concrete examples (target ticker, address, research notes). Mentions scoping and pairing, but does not explicitly exclude alternative tools.

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

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

The annotation set (readOnlyHint, idempotentHint, destructiveHint) already covers safety. The description adds valuable details: response fields (source, citation_uri, raw payload), the mark_read flag behavior (flagging events as read to filter next calls), and polling suitability, none of which 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 concise—multiple sentences packed with useful information without redundancy. It is front-loaded with the main action and efficiently covers purpose, parameters, behavior, and alternative access.

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?

Although there is no output schema, the description explains that each alert carries source, citation_uri, and raw event payload. It also mentions polling and an alternative GET endpoint. For a simple read-only tool, this is sufficient; a fully detailed return structure would earn a 5.

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

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

With 100% schema coverage, the baseline is 3. The description adds context beyond the schema, such as example filter values (e.g., 'sec_8k') and clarifying that mark_read flags events as read to show only newer ones on subsequent calls, enhancing parameter understanding.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, specifying the verb 'pull' and the resource 'subscription feed'. It distinguishes itself from siblings like 'list_subscriptions' and 'recent_changes' by focusing on recent alerts.

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 notes that polling works fine and mentions an alternative REST endpoint for scripts and dashboards, providing context on when to use the tool. However, it lacks explicit guidance on when not to use it relative to 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?

Annotations declare readonly and idempotent. Description adds fan-out to multiple sources, fallback logic from GDELT to GNews, soft-fail for USPTO, and return structure with citation URIs. 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?

Long but efficiently structured with example queries upfront. Every sentence adds information. Could be slightly more concise, but complexity justifies 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 3 params and no output schema, the description explains return structure, sources, fallback, and provides an alternative. Covers edge cases like USPTO sunset. Complete for the tool's purpose.

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 100% gives baseline 3. Description adds practical examples for 'since' (e.g., '30d'), explains 'type' is only 'company', and clarifies 'value' accepts ticker or CIK. Adds value beyond schema.

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

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

The description clearly states it provides a change feed for a company in a date window, listing sources and output. It distinguishes from sibling 'entity_profile' by specifying when to use the alternative.

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

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

Explicit example queries show when to use, and the description directly says 'Use entity_profile instead when you want the static profile', giving clear when-not and alternative.

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?

Adds key behavioral details beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradiction.

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

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

Three sentences, front-loaded with main purpose, then usage guidance, then behavioral details. 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?

Covers purpose, usage, and behavior well. Lacks mention of return value or overwrite behavior, but annotations and simplicity make it acceptable.

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

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

Schema coverage is 100% and parameter descriptions are adequate. The description adds context but does not elaborate on parameter details beyond the schema.

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

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

The description clearly states the verb ('Save') and resource ('data') and explicitly 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?

It provides explicit guidance: 'Use when you discover something worth carrying forward' and explains pairing with recall/forget. Also mentions persistence differences.

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 well beyond the annotations, disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, and the 'figi_candidates' behavior for ambiguous matches. This rich behavioral detail complements the readOnly/openWorld/idempotent hints without contradicting them.

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

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

The description is long but well-structured, front-loaded with user-intent examples and organized around supported types and key behaviors. While every sentence mostly earns its place, some details could be tightened without losing meaning; the density is high but not wasteful.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers input handling, supported entities, return identifiers (CIK, ticker, LEI, FIGI, RxCUI), ambiguity behavior, unresolved identifiers, degradation, and internal multi-step execution. An agent has enough context to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, but the description adds substantial semantics beyond the schema: it explains what each enum type resolves to, gives input format guidance for 'value', warns against including full noun phrases, and even explains ISIN-to-LEI resolution. This is exemplary parameter-level documentation.

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 verb ('resolve'), its resource ('user-spoken NAME to canonical/official identifiers'), and its role as the first stop when an ID is needed. It differentiates from sibling tools like entity_profile and compare_entities by explicitly framing itself as the resolver for identifiers other tools require as input.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID', supported by concrete user-phrase examples. It also explains the tool's scope across company and drug types, and describes tricky cases like bond issuer names. It does not explicitly list exclusions or alternatives, but the context is strong enough to guide selection.

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

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

Annotations already set readOnlyHint, idempotentHint, etc. Description adds significant detail: that it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, signal density per entity.

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

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

Four sentences with no wasted words. First sentence captures core purpose, followed by brief behavioral details and a concrete use case. Efficient 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?

Given the tool's complexity (multi-entity, internal probe), the description covers what it does, how it works (calls ai_visibility_check), and what it returns (ranked list with scores). Lacks explicit format or definition of 'signal density', but sufficient for a tool that delegates. No output schema, but description compensates well.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by noting that the first entity in the array is treated as the 'subject' for narrative, and that context is shared across probes. This goes beyond schema descriptions.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side' with specific verb (compare) and resource (AI visibility). It distinguishes from sibling ai_visibility_check by emphasizing batch comparison and ranking.

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 case ('competitive AI-marketing audits') and example question. Does not explicitly mention when not to use or alternative tools like ai_visibility_check for single entities, but context implies it.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: partial failure behavior (bundlephobia can take 5-30s, sources_failed will list it), graceful degradation, and the composite nature of the call. 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 relatively long but each sentence provides useful information. It is front-loaded with the main purpose and then details behavior. Could be slightly more concise, but no wasted 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?

Even without an output schema, the description thoroughly documents the return fields (summary block with is_latest, license, etc., per-advisory detail, links, alternative versions). It also covers edge cases (scoped packages, default version, timeout behavior). Very complete for a read-only 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% for both parameters. The description adds context that 'package' accepts scoped names (e.g., '@types/node') and that 'version' defaults to latest when omitted. This adds marginal value beyond the schema descriptions.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, covering license, advisories, version history, and bundle size. It distinguishes from sibling tools by mentioning NPM ecosystem only and referencing 'deps.dev:version' 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?

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes that PyPI/Maven/Cargo/Go fall under a different tool ('deps.dev:version'). This provides clear when-to-use and alternative 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, destructiveHint. Description adds technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', truncation flag for >200K, and output format (passages with offsets and scores). 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?

Compact 80-word description with three focused sentences: first states purpose, second gives usage guidance, third provides technical implementation details. Every sentence is informative. No filler.

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

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

Given no output schema, description covers input parameters, behavioral details (embedding model, window size, character limit), output format (passages with offsets and scores), and links to sibling tool ask_pipeworx_grounded. Fully sufficient for 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 covers 100% of parameters. Description clarifies text as 'document text to search inside (max ~200K chars)', query as natural-language with examples, and limit as 'Max passages to return (1-20, default 5)'. Adds value beyond schema by explaining output structure (offsets, scores) and retrieval mechanics.

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?

Clear verb+resource: 'Semantic search INSIDE a fetched record.' Distinguishes from siblings by explaining it searches inside a pre-fetched document, unlike ask_pipeworx_grounded which grounds over passages. Includes specific examples like 'SEC 10-K body'.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Mentions pairing with ask_pipeworx_grounded for grounding. Also describes input cap (200K chars) and truncation behavior.

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 significant behavioral details beyond annotations, such as the need for a Pipeworx OAuth account, type-specific parameters, SMS delivery cap, webhook auto-disable after 10 failures, and the one-time signing secret. Annotations only indicate idempotency and non-destructiveness, which are consistent.

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 fairly concise given the complexity, with well-structured sentences covering purpose, requirements, types, and delivery. It could be slightly shorter, but it is efficient and front-loaded with the main action.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is very complete, covering all necessary details: account requirements, type-specific params, delivery options, limitations (caps, auto-disable), and security (signing). It leaves no significant 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%, and the description adds detailed semantics for each parameter, including type-specific structures, examples, and constraints (e.g., SMS must be verified, webhook HTTPS only). It provides more value than the schema alone, justifying 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on subscription creation.

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

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

The description provides clear context on when to use the tool, including OAuth account requirements, supported types with examples, and delivery channel options. It does not explicitly state when not to use it, but the context is sufficient 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining it returns example questions with tool calls and is an onboarding tool. 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 moderately long but efficiently packed with useful info: trigger phrases, output description, usage instructions. Could be slightly trimmed but not verbose.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers all needed aspects: what it returns, when to use, and how to use the param. Sibling context and annotations complement it well.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond schema by listing possible topic values (finance, pharma, etc.) and explaining omission behavior ('full spread'). This extra context justifies a 4.

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 with exact tool+argument shapes. It uses specific verb 'returns' and distinguishes from siblings like ask_pipeworx by noting it should be used first when unsure 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, or to learn how to call the meta-tools'. Also explains when to omit or pass a topic. Does not explicitly state when not to use, but context is clear.

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

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

Annotations indicate non-read-only, idempotent, and non-destructive. The description adds ownership enforcement and deactivation (not deletion) details, which go beyond annotations and inform agent about side effects and data persistence.

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

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

Two sentences, front-loaded with action and key constraints. No superfluous words; every sentence adds value.

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

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

While the description is clear about the effect, it omits any indication of the return value (e.g., success confirmation, count). Given no output schema, this is a minor gap for completeness.

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

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

The sole parameter 'id' has 100% schema description coverage. The description only mentions 'by id' without additional semantic detail, so it does not significantly enhance what the schema already provides.

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

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

The description clearly states the verb ('Cancel') and resource ('subscription by id'), and distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' (read). It also specifies ownership enforcement and deactivation behavior, adding specificity.

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: ownership is enforced (only own subscriptions), and deactivation preserves historical events accessible via 'recent_alerts'. This helps the agent decide when to use this tool versus deletion or other operations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by detailing the decoding behavior (bank code, plaza, account number) and bank name resolution. 'Pure computation' aligns with annotations, and no contradictions are present.

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 concise sentences, front-loaded with the core purpose. Every sentence adds value with no redundant or filler content.

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

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

The description covers validation behavior and input flexibility but omits any mention of the output format or return value. Given the lack of an output schema, this gap reduces completeness for an AI agent that needs to interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds behavioral context about what the tool does with the parameter (checksum, decoding) but does not significantly enhance parameter semantics beyond the schema's format description.

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

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

The description clearly states the tool validates a Mexican CLABE, checks the control-digit checksum, decodes bank code, plaza, account number, and resolves bank names. It is specific and distinguishes itself from sibling validation tools like validate_cpf and validate_cnpj.

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 this tool (for Mexican CLABE validation) and notes that it is a pure computation accepting spaces/dashes. It does not explicitly mention alternatives or exclusions, but the specificity makes usage intuitive.

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, openWorldHint, idempotentHint), the description discloses critical behavioral nuances: the meaning of 'could_not_verify' (check did not happen, carries verification_error, not evidence), 'unsupported' (no source), and the return structure (verdict, grounded value with pipeworx:// citation, reasoning). 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?

Despite being detailed, the description is well-organized and front-loaded with usage examples. Every sentence adds value: pipeline explanation, return values, warnings about verdict semantics, and the efficiency benefit. It is appropriately sized for a complex tool 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?

Even without an output schema, the description fully covers what the agent can expect: verdict list, actual value with citation, reasoning, error semantics, and routing behavior. The context is complete enough to select and invoke the tool correctly in a variety of factual claims.

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

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

Schema coverage is 100% for both parameters, and the description adds meaningful context: tolerance_pct is explained as an override with default behavior ('implied by wording, capped at 5') and specific use cases (1–2 for hallucination detection). Claim examples illustrate expected input format, enriching the schema.

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

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

The description clearly identifies the tool as a natural-language claim verifier against authoritative sources, with specific examples ('Is it true that…', 'fact check', 'verify the claim that…'). It distinguishes itself from sibling validation tools (like validate_cpf) by focusing on factual claims and mentions a consolidated workflow replacing multiple calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company-financial claims vs other facts, and mentions it replaces 4–6 sequential calls, giving clear context for when to invoke this tool instead of a multi-step pipeline.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context: support for numeric and alphanumeric CNPJ, punctuation acceptance, and the skip_lookup flag behavior. No contradictions.

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

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

Three sentences, front-loaded with the primary purpose. Every sentence adds value: validation + lookup, format details, skip_lookup option. No unnecessary words.

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

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

The description covers the main functionality and parameters well. No output schema, but the description mentions what data is returned. For a simple validation tool with annotations, this is nearly complete. Minor gap: no mention of error handling or status codes.

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 includes detailed descriptions. The description adds minor context (checksum support, punctuation) not present in schema for the cnpj param, but otherwise does not significantly enhance understanding 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 it validates a Brazilian CNPJ and looks up company registration details. It uses specific verbs (validate, look up) and identifies the resource (CNPJ). The sibling tools include validate_cpf and validate_clabe, so the target entity is distinct.

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

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

The description implies when to use (to validate a CNPJ) but does not explicitly compare to siblings or state when not to use. It could mention, for example, that validate_cpf is for individual tax IDs. The guidance is adequate but not explicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral traits: it is a pure computation (no lookup), returns check-digit correctness and formatted form, and accepts punctuation. This adds value beyond annotations without contradiction.

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

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

The description is concise: two efficient sentences that front-load purpose and behavior. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's simplicity (one parameter, clear annotations, no output schema), the description covers the essential aspects: what it does, how it works, acceptable input, and what it returns. It could mention return structure more explicitly, but overall it is sufficiently 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?

The input schema covers the parameter fully with description and examples. The description confirms accepted formats (with punctuation) but adds no extra semantic information beyond what the schema already provides. With 100% schema coverage, 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 identifies the tool's purpose: validating the checksum of a Brazilian CPF. It specifies the resource (CPF), the verb (validate), and scope (checksum computation, no lookup). It distinguishes from sibling tools like validate_cnpj and validate_clabe by being CPF-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?

The description implies usage context: use it when you need to validate CPF checksum computationally. It mentions 'no lookup' which hints at limitations, but does not explicitly state when not to use it or provide alternatives. Given sibling tools exist, the context is clear enough.

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