Data Toulouse

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds that it returns per-model data and clarifies cost implications (free default, BYO key for Anthropic). No contradictions; it supplements the annotations well.

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: action, default, key parameter, return format, and use cases. Every sentence provides essential information 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?

No output schema exists, but the description outlines the return structure (per-model fields + combined view). For a tool with 4 parameters and moderate complexity, this is adequate for an agent to understand inputs and outputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: examples for 'entity', lists supported 'models', explains when '_apiKey' is needed, and clarifies 'context' role for disambiguation. This goes beyond the schema's descriptions.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes itself from sibling tools like 'ask_pipeworx' or 'compare_entities' by focusing on multi-model visibility auditing.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter. While it doesn't list alternatives, the context is sufficient for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context: it routes to 5,798 tools, fills in arguments, and returns answers with stable pipeworx:// citation URIs. This goes beyond the annotation-only picture, though it does not detail error or edge-case behavior.

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

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

The description is long but front-loaded with the most important guidance, and includes concrete examples and alternative tool routing. Some repetition and a slightly garbled transition between deep_research guidance and breaking-news notes add minor noise, but each section generally earns its place.

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

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

For a tool with no output schema and one required parameter, the description covers the tool's purpose, typical queries, example inputs, return behavior, and when to choose alternatives. It is quite complete, though a note about potential limitations or failure modes would make it fully self-sufficient.

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

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

Schema coverage for parameters is 100%, so the schema already documents the question field and its aliases. The description adds examples of natural-language queries but does not add new semantic detail beyond what the schema provides. The baseline of 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?

The description clearly identifies the tool as a router that answers factual questions by selecting from thousands of tools and returning structured answers with citation URIs. It explicitly distinguishes itself from web search and names specific sibling alternatives, making its purpose and scope unambiguous.

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

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

The description gives explicit 'use whenever' triggers, examples, and clear routing guidance to alternatives like ask_pipeworx_grounded and deep_research. It even states preference over web search, leaving little ambiguity about when this tool should be selected.

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

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

The description goes beyond the readOnly/idempotent annotations by explaining the beta nature, live candidate routing improvements, current absence of an active candidate, and that it is a full working router with no fallback. This is valuable behavioral context that helps an agent calibrate expectations. No contradiction with the annotations is 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 longer than strictly necessary but every part contributes: beta status, functional equivalence, current state, usage guidance, and no-fallback guarantee. The structure front-loads the most important identity information and then adds context. Minor redundancy exists in repeating 'full working router' and 'experimental edge', but overall it is 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 simple single-required-parameter schema and rich annotations, the description covers the key operational aspects: how to use it, current behavior, and relationship to the stable router. It references 'same response shape' rather than describing the output schema, which is acceptable if the agent knows ask_pipeworx, but a direct description would be more self-contained.

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

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

Schema description coverage is 100%, with every parameter documented as an alias for 'question'. The description adds no further parameter semantics beyond saying the tool accepts 'same arguments' as ask_pipeworx. Per calibration, the baseline of 3 applies because the schema already carries the parameter burden.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' and explains it is an identical universal router with 5,798 tools, same arguments, and same response shape. It differentiates from the sibling ask_pipeworx by its experimental routing edge. It does not fully define what 'ask_pipeworx' itself does, but this is sufficient given the explicit comparison.

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

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

The description explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It also clarifies that currently no candidate is active, so it behaves identically to ask_pipeworx right now. It gives clear context and names the relevant alternative, though it does not explicitly state 'when not to use' scenarios.

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

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

The description discloses the full success response shape (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and the explicit refusal contract with enumerated refusal_reason values. This goes well beyond the annotations, which only declare readOnly, openWorld, idempotent, and non-destructive. 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?

Every sentence earns its place: the first states purpose, the second explains routing and extraction behavior, the third details the return/refusal contract, and the fourth gives usage guidance and cost comparison. Front-loaded and dense 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?

Because there is no output schema, the description fully supplies the return object and failure modes. Combined with rich annotations, explicit usage boundaries, and the alternative tool mention, an agent has everything necessary to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, with 'question' fully described and five aliases (q, text, input, query, prompt) documented. The description adds no additional parameter semantics, and none are needed since the schema already carries the full burden. 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?

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by emphasizing that answers are extracted only from tool results. The specific verb 'EXTRACTS' plus the structured evidence output makes the purpose concrete and differentiated.

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

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

Explicit guidance is provided: use when an answer 'will be quoted, cited, or acted on' and facts must not be invented, with specific domains listed. It also names the alternative ask_pipeworx and states the cost tradeoff, telling the agent to 'prefer ask_pipeworx for casual lookups'.

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

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

The description discloses extensive behavioral traits beyond annotations: low-confidence short-circuiting, closed market handling, wide-spread warnings, resolution-rule risk parsing, parent event extraction, and news fallback mechanisms. Annotations are readOnlyHint/idempotent, and the description adds critical context 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 long but well-structured and front-loaded with the core purpose. Every sentence adds useful information (examples, edge cases, safety notes). It could be slightly more concise, but the detail is necessary given the tool's complexity.

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

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

Given the lack of output schema, the description thoroughly explains response shapes, resolver contract, parent event extraction, news fields, and safety mechanisms. It covers edge cases like closed markets, illiquid spreads, and cancellation rules, making the tool's behavior fully predictable.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds value by explaining the fan-out logic and response shapes for each classifier, and clarifies the depth parameter with examples. This exceeds the 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 description clearly states the tool researches a Polymarket bet using a slug, URL, or question text, and returns an evidence packet with comparison. It explicitly lists use cases ('should I bet on X') and distinguishes from sibling tools like polymarket_edges by the 'research' framing and specific fan-out examples.

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

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

The description provides explicit use cases and examples for when to use the tool. It advises inspecting market_match_confidence before trusting results, and notes that low-confidence or closed markets return special statuses. While it does not directly name alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already provide read-only, idempotent, non-destructive hints. Description adds specific behavioral traits: data sources (EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction.

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

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

Description is fairly concise but slightly verbose (e.g., multiple examples). Front-loaded with the core purpose. Every sentence adds value, but could tighten.

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

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

Given no output schema, description adequately explains return data (paired data + citation URIs) and covers both entity types. Handles edge cases like off-calendar fiscal years. Comprehensive for a comparison tool.

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

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

Schema coverage is 100%, but description enriches meaning: explains that type='company' pulls financial metrics from SEC filings, type='drug' pulls adverse events and trial counts; for values, specifies tickers/CIKs for companies, names for drugs.

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 performs side-by-side comparison of 2-5 entities in one call, distinguishing from sequential lookups. Includes specific verbs like 'compare', 'rank', 'head to head' and resources (companies/drugs).

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Lists example queries and explains when for each entity type. Clear context and exclusion of alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's burden is lower. It adds value by specifying the type of data returned (fields/schema, themes, record count) and the usage hint, without contradicting annotations.

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

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

The description is a single sentence that clearly conveys purpose and usage hint without unnecessary words. Every part is informative and earns its place.

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

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

For a tool with one parameter, full schema coverage, rich annotations, and no output schema, the description is complete. It states what is returned and provides a usage recommendation, which is all that is needed.

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

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

With 100% schema coverage for the single parameter, the description does not need to add more. The schema already describes dataset_id as coming from search_datasets. Description adds no extra parameter details, so baseline score of 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?

The description clearly states the verb 'Get metadata' and the specific resource 'one Toulouse Métropole Open Data dataset'. It distinguishes from siblings by specifying it returns fields/schema, themes, and record count, which is different from search_datasets and query.

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

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

The description explicitly says 'call before query to learn the column names', providing clear context for when to use. It does not mention when not to use or list alternatives, but the sibling context implies query is the alternative for data retrieval.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the internal decomposition process, parallel routing, gap reporting with gaps[], contradiction handling for standard/thorough, citation_uri fetchability semantics, excerpting behavior, and latency expectations. No annotation contradiction exists.

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

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

Every sentence carries unique information, but the description is a dense wall of text with long clauses, embeddings, and run-on punctuation. It is front-loaded with account requirements and the core value proposition, though better organization would improve parseability.

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 high complexity, no output schema, and no nested params, this description is remarkably complete: it covers auth/tier requirements, scope, result packet contents, gap handling, citation behavior, contradictions, parameter semantics, and expected latency. Nothing material is left for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that depth:'thorough' requires a paid plan, explaining the hop/recovery behavior for standard and thorough, and providing concrete example questions for the question parameter.

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

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

The description identifies a specific verb and resource: research across 1,517 structured data sources in one call, decomposing questions into facets and routing to tools in parallel. It also explicitly distinguishes itself from open-web search and from the ask_pipeworx sibling, making its scope unmistakable.

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

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

It states clear when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly says to use ask_pipeworx for single lookups or when not signed in. This is actionable routing guidance that sharpens tool 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds transparency by explaining the tool returns top-N relevant tools with input schemas, ready to call directly, which goes 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?

The description is moderately long but well-structured, with the core purpose front-loaded. It efficiently lists domains and explains return characteristics. Could be slightly more concise, but every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains what the tool returns (top-N relevant tools with names, descriptions, full input schemas, curated examples). It also specifies default limit and max limit. This is sufficient for a discovery tool, though details on how relevance is determined are omitted.

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 query parameter accepts multiple aliases (task, q, description, search) and provides examples. This semantic detail helps the agent understand flexibility beyond what the property descriptions alone convey.

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

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

The description clearly states it finds tools by describing data or task, lists many specific domains (SEC filings, financials, FDA drugs, etc.), and explains it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools like query or search_within, which have different purposes.

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

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

Explicit usage guidance: '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 and want to see the option set (not just one answer).' This tells the agent when to use it and implicitly when not to (single answer).

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 behavior beyond the readOnly/openWorld/idempotent annotations: it fans out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF, and explains sources_used/sources_failed, that empty sections mean real 'no data', and that private companies return resolved:false. This gives the agent an accurate mental model of what happens inside the tool.

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

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

The description is long but front-loaded with query examples and the key 'one parallel call' behavior before enumerating sources and returns. Nearly every sentence adds needed information, though the type-interchangeability note largely repeats the schema and the 'person/place coming soon' aside is low-value for current invocation.

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 present, the description carries the burden of explaining return shape and does so well: it enumerates main result sections (cik, company_name, recent_filings with URIs, fundamentals, patents, contracts, fda products, hiring, news, LEI) and clarifies sources_used/sources_failed and empty-section semantics. The agent can invoke and interpret the result without guessing.

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

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

Schema description coverage is 100%, and both parameters are already well described: type enumerates 'company'/'ticker' and value documents ticker, CIK, and company-name forms. The tool description mostly repeats this and adds some related behavior (name resolution, resolved_from/resolved_to, private-company notes), but it does not substantially enrich the meaning of the parameters 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 states a specific action and resource: 'full cross-source profile of a US public company' delivered in one parallel call. It also distinguishes itself from chaining single-pack SEC/XBRL/news lookups explicitly, so an agent can recognize when this tool is the intended holistic 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?

It lists concrete trigger phrases like 'Tell me about X,' 'research Acme,' and 'brief me on Tesla,' then gives an explicit preference rule: ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view. It also covers the private-company case, telling the agent that resolved:false with a notes line is the expected outcome rather than a failure.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and handling stale context, going beyond annotations to inform the agent of appropriate scenarios.

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 core action, followed by usage guidance. Every sentence adds value with zero waste.

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 1-required-parameter tool with no output schema, the description covers purpose, usage context, and related tools completely. No gaps remain.

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

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

Schema coverage is 100% and parameter description is adequate ('Memory key to delete'). Description does not add new information about the parameter beyond what schema provides, so 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?

The description clearly states 'Delete a previously stored memory by key' with a specific verb (delete), resource (memory), and method (by key). It is distinct from sibling tools like 'remember' and 'recall'.

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

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

Explicitly tells when to use ('context is stale, task done, clear sensitive data') and mentions paired tools ('Pair with remember and recall'). No exclusions 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?

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds details: fetches the page, extracts title/description/key links, emits standard llms.txt markdown. This goes beyond annotations by describing the extraction and output format.

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 compact sentences, each sentence serves a purpose: what, how, output format, use cases. No fluff, well front-loaded.

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

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

Given simple tool with 2 params and no output schema, description explains process, output format, and use cases. Could mention error handling or limits, but overall 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 description adds little beyond schema. 'max_links' default and max are repeated. No additional semantic enrichment.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, with specific verbs like 'fetches', 'extracts', and 'emits'. Distinguishes from siblings by being unique; no other sibling tool does this.

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

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

Explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor's AI crawl. Lacks explicit when-not-to-use or exclusions, but provides clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by explaining the return structure and the include_inactive parameter behavior, which is beyond annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. Every sentence earns its place with 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?

Tool is simple (one optional param, no output schema). Description covers all needed aspects: purpose, return fields, when to use, and parameter implication. Fully 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 description coverage is 100% and already describes the include_inactive parameter. Description adds marginal value by implying default behavior ('active subscriptions') but doesn't add new meaning beyond schema.

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

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

Description clearly states 'List the caller's active subscriptions' and lists return fields (id, type, etc.). It distinguishes from sibling tools like subscribe/unsubscribe by specifying it's for reviewing existing subscriptions.

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

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

Explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and hints at alternatives (subscribe/unsubscribe).

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 are all false and carry minimal meaning, so the description carries the full burden. It discloses behavior well beyond annotations: filing without an account returns a claim_token, passing that token later returns resolution status, the tool is rate-limited to 5 per identifier per day, it is free, and the team reads digests daily. This gives the agent accurate expectations for side effects and constraints.

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

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

The description is front-loaded with the core purpose and then efficiently covers operational details without redundancy. Each sentence adds distinct value—exclusivity scope, message content guidance, claim_token flow, rate limit, and cost—so the length is justified.

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 four parameters, nested context objects, no output schema, and no helpful annotations, this description is exceptionally complete. It explains the tool's purpose, when to use it, what to include, how to follow up via claim_token, exclusions, rate limits, and impact—leaving little ambiguity for an agent deciding to invoke it.

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

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

Although the schema fully describes all parameters, the description adds high-value usage semantics: a concrete example for claim_token ('pwfb_…'), the instruction that claim_token must be passed with no other arguments, a length guideline for message (1-2 sentences, 2000 chars max), and emphasis on not pasting the end-user's prompt. These details meaningfully improve parameter handling 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback types (bug, feature, data_gap, praise) and distinguishes this tool from sibling query/assistant tools like ask_pipeworx by framing it as direct feedback to the Pipeworx team rather than a data inquiry.

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 for each feedback type and a strong exclusion: do not file issues for tools from other MCP servers; file those with the original server. It also instructs users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, making the intended invocation clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), caching (5min-1h depending on window), and that it's self-aggregating. This adds significant value beyond annotations.

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

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

The description is three sentences with bullet points for use cases. It front-loads the main purpose and is efficient, though slightly wordy. Every sentence adds value; no redundancy.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description sufficiently explains what to expect: top tools, top packs, total call volume. Annotations cover safety. It could mention response format explicitly, but overall adequate.

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

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

Schema coverage is 100% with one parameter (window) having enum and description. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond the schema's basic enum 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 it returns top tools, top packs, and call volume over a window. It lists three specific use cases (discovering hot data, confirming canonical tool, checking alignment) and distinguishes itself from siblings by focusing on trending/usage data rather than answering queries.

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 three explicit use cases for when to use this tool. While it doesn't explicitly state when not to use it, the context of sibling tools like ask_pipeworx implies alternatives. The guidance is practical and helps the agent 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 indicate read-only, idempotent, non-destructive behavior, and the description adds extensive behavioral details: how arbitrage is found (monotonicity violations, partition-sum checks), response structure, fill check logic, semantic anchor similarity threshold, partition filter for placeholders, and conditions when not to trade (realizable_edge_pp ≤ 0). No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the main purpose, but it is somewhat lengthy due to detailed technical explanations of internal algorithms. Every part is informative, but could be slightly more concise without losing clarity.

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

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

Given no output schema, the description thoroughly explains the response structure for both modes, including fields like gap_pp, suggested_trade, reasoning, monotonicity context, partition_check details, and fill check. It also covers edge cases and limitations (e.g., do not trade when realizable_edge_pp ≤ 0). The tool is fully specified for its complexity.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic' parameters. The description adds extra context: examples of event slugs, that full URLs are accepted, examples of topic seed questions, and explains the effect of each parameter in detail (single-event vs cross-event mode).

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings by naming specific methods and modes (trending_scan, event, topic).

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 each mode: call with no args for trending_scan, pass 'event' for a specific market, 'topic' for cross-event scanning. It also recommends 'event' for specific markets and directs to sibling 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?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description goes beyond by disclosing that the tool is cached for 1 hour at the KV level, returns diagnostics to explain empty segments, includes a 24h-move warning, and details response structure. 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 quite long but well-structured, starting with an overview, then detailing model families, response fields, and parameter knobs. Every sentence appears to add value given the complexity of the tool. It is not overly verbose for the information it conveys, though it could potentially be slightly more concise.

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

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

Despite the absence of an output schema, the description thoroughly explains the return values, including the segments (model_driven, structural_arbitrage, concentrated_longshot), the fields within each opportunity (edge_pp_net, kelly_fraction, etc.), and diagnostics. It also covers how parameters affect output and edge cases like Fed bets. The tool is complex, but the description is complete for an agent to understand and use it effectively.

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

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

All 9 parameters are described in the schema with 100% coverage. The description adds significant additional context for several parameters, such as explaining that min_kelly does not filter partition arbs (it applies to single-leg opportunities), and providing guidance on slippage_pp and max_spread_pp defaults. This enrichment justifies a score above the baseline of 3.

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

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

The description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb-resource pair that clearly defines the tool's purpose. It also distinguishes itself from sibling tools like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by specifying it is built for 'what should I bet on today' and that it discovers opportunities without paging hundreds of markets.

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 (for discovering betting opportunities), how to configure parameters (e.g., slippage_pp: 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'), and explains why certain knobs exist (e.g., min_kelly doesn't filter partition arbs). It also clarifies edge cases like Fed bets and how filters work, giving comprehensive usage advice.

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 safe read-only and idempotent behavior. The description adds rich behavioral context: it reads snapshots, returns time-series data, first_seen, trend, decay, and explains limitations like snapshot gaps and 60-day TTL. 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 somewhat lengthy but well-structured: purpose first, then response structure, then limitations. Every sentence adds necessary information, though some trimming of repetitive details could improve conciseness.

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

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

Despite no output schema, the description thoroughly explains the return format (tracked, expired, snapshot_dates) with detailed field meanings. It covers complexity (trend computation, decay per day, expiration) and limitations, making it complete for agent use.

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

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

Schema coverage is 100% with basic descriptions. The tool description adds value by explaining how 'days' and 'window' affect the output (e.g., snapshot_dates, default values) and their role in the analysis, going 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about an edge's age and decay. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on longitudinal analysis 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 explains that it answers 'how long has this edge existed and is it shrinking?' and contrasts a fresh wide edge with an old one, implying when to use. However, it does not explicitly mention when not to use or alternatives like 'polymarket_edges' for current edges.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds detail on what happens (walks the ladder, returns verdict) and warns about thin books and forced directional risk, without contradicting annotations.

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

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

Well-structured with clear sections (single-market, basket) and uses marked roles like 'SINGLE-MARKET:' and 'BASKET:'. Some redundancy but overall efficient. Good front-loading of 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?

Despite no output schema, the description lists all return fields for both modes, explains the verdict, and relates to sibling tools. It covers both usage contexts thoroughly.

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 significant meaning: explaining single-market vs basket modes, default sides, and interpretation of size_usd as settlement notional in basket mode. This elevates the score.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explains two distinct modes (single-market and basket). It also distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risk of partial basket fills converting an arb into an unhedged position, providing clear guidance on when to use.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, and the description adds substantial behavioral detail: it does not model Kalshi fees (spreads are gross), matching is keyword/token-overlap rather than a shared resolution source, null temporal alignment does not mean aligned, and returned pairs may still carry compatibility codes that must be read.

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 front-loaded with a crisp one-sentence definition and uses clear structural cues (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) so key facts are scannable. Some sentences are dense enough that a shorter version is possible, but no part is 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 carries the full burden of explaining return shape, safety fields, error/edge semantics, fee caveats, and skipped-comparison counters. It covers all of them, including subtle null-vs-false semantics and the warning that compatibility codes can be present even when matched_pairs>0.

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 still adds real semantic value: it explains that topic auto-fetches the matching event on each venue, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same token-overlap matcher. This tells an agent how the optional parameters interact, which the schema alone does not.

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 the verb and resource directly: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The description goes on to specify two concrete modes, which makes the tool unmistakable and clearly distinct from the Polymarket-only siblings like polymarket_edges.

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

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

The description gives actionable use context: use the topic shortcuts for pre-mapped macro events, or use explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also flags when the result will be unreliable ('pre-mapped ≠ tradeable') and notes that many topics return compatibility warnings, but it does not explicitly compare against alternatives such as polymarket_arbitrage.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool uses ODSQL, which is a specific query language, providing useful behavioral context beyond annotations. It does not contradict annotations.

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

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

Two sentences: first states purpose and resource, second lists capabilities. No fluff, front-loaded with essential information. Every word earns its place.

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

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

No output schema, but the description covers the main operations and examples exist in the input schema. It lacks specification of the return format (e.g., JSON array), but for a query tool with rich schema, 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by summarizing parameter groups (filter, aggregate, sort, paginate) and noting that `where` overrides `query`, which is not explicitly stated in the schema.

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

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

The description clearly states the verb 'Query' and the resource 'records from a Toulouse Métropole Open Data dataset with ODSQL'. It specifies operations (filter, aggregate, sort, paginate) and distinguishes from sibling tools like search_datasets by emphasizing the ODSQL query language.

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 'Query records with ODSQL', indicating when to use it. It does not explicitly exclude alternatives or state when not to use it, but the context is clear enough for agents to infer 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the dual behavior (retrieve by key or list all). This provides context beyond the annotations.

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

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

The description is three sentences with no wasted words. The first sentence immediately states the primary action, and subsequent sentences add context and usage guidance. Every sentence earns its place.

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

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

Given the tool's low complexity (single optional parameter, no output schema), the description fully covers purpose, usage, behavior, and parameter semantics. It is complete for an AI agent to select and invoke correctly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaning by explaining that omitting the key lists all keys, which is not fully captured in the schema's 'omit to list all keys' note. This clarifies the parameter's optional behavior.

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

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

The description uses specific verbs ('retrieve', 'list') and clearly identifies the resource ('value previously saved via remember', 'all saved keys'). It effectively distinguishes itself from sibling tools 'remember' and 'forget' by describing complementary actions.

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 concrete use cases (look up ticker, address, research notes) and explains the tool's purpose ('without re-deriving it from scratch'). It mentions scoping and pairing with remember/forget. However, it does not explicitly state when to avoid using this tool or list alternatives among siblings.

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

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

The description explains the behavior of mark_read (flags events as read to exclude from next call) and the structure of returned events. Annotations already declare readOnlyHint=true, which is contradicted by mark_read's state change, but description adds useful 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 front-loaded with the core purpose in the first sentence. It is relatively concise at four sentences, but includes an extra detail about the GET endpoint that could be considered tangential. Still clear 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?

The description covers the key aspects: what the tool returns (source, citation_uri, payload), filtering options, mark_read behavior, polling suitability, and an alternative access method. No output schema exists, but the description adequately describes what to expect.

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, baseline is 3. The description adds practical context: provides an example type filter ('sec_8k'), clarifies mark_read's effect on future calls, and explains the format of 'since'. This elevates the value beyond 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: 'Pull fired events from your subscription feed' and specifies what each alert carries (source, citation_uri, payload). It is specific and distinguishes itself from sibling tools like 'recall' or 'recent_changes' by focusing on subscription feed 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 provides usage guidance: filtering by type and since, using mark_read to avoid duplicates, and notes that polling is acceptable. It also mentions an alternative GET endpoint for scripts, aiding in when to use this tool versus other methods.

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

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

Describes parallel fetching, fallback from GDELT to GNews, USPTO soft-fail, and return structure. Consistent with annotations (readOnlyHint, idempotentHint, destructiveHint=false). 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?

Information-dense but well-structured: starts with examples, explains behavior, then alternative tool. Could be slightly more concise but no wasted sentences.

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 3 params and no output schema, the description fully explains input formats, sources, fallback, limitations, and return structure. Complete for effective use.

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

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

Schema coverage is 100%, but description adds usage hints like recommended 'since' format and example values. Adds meaning beyond schema.

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

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

The description clearly states the tool is a change feed for a company over a time window, listing specific sources (SEC, GDELT/GNews, USPTO) and distinguishing it from entity_profile. Example queries clarify the intent.

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

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

Explicitly says to use entity_profile for static profiles, implying this tool is for recent changes. Provides guidance on when to use each 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?

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier', which enriches understanding 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 4 sentences, front-loaded with the core purpose, then usage, then storage details, then partner tools. Every sentence earns its place; no fluff.

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

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

For a simple tool with 2 required params and no output schema, the description is complete: it covers purpose, usage context, persistence behavior, and related tools. No gaps remain.

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

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

Schema coverage is 100%, baseline is 3. The description adds practical examples for 'key' ('subject_property', 'target_ticker') and clarifies 'value' can be 'any text', adding meaning beyond the schema's descriptions.

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides concrete examples like 'a resolved ticker, a target address, a user preference'. It distinguishes from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

The description gives explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also states to pair with 'recall' and 'forget', covering when to use and when not to.

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

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

The description adds substantial behavior beyond the readOnly/idempotent/openWorld annotations: graceful degradation when GLEIF or OpenFIGI is down, no assertion when multiple instruments match and figi_candidates is returned, explicit listing of unresolved identifiers, and source labeling for every identifier. This is deep, non-obvious behavioral context.

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

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

The description is long and dense, but the most important use case is front-loaded and the supported types are clearly labeled. Some schema-level details are repeated, so it is not maximally tight, but there is no filler and every major clause contributes useful information.

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

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

With no output schema, the description carries the full burden of describing return behavior, and it does so thoroughly: it enumerates the identifiers returned for each type, explains unresolved handling, describes candidate ambiguity, notes enrichment degradation, and gives a citation format for drugs. An agent has enough to call and interpret the tool correctly.

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

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

Schema coverage is 100%, but the description supplements the schema with meaningful details: it adds ISIN as an accepted company input not listed in the schema, clarifies that entity names must be the exact printed issuer name, and warns against including security-class words like 'revenue bonds.' This goes beyond what the schema alone 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 states a precise action: resolve a user-spoken name to canonical/official identifiers that other tools require as input. It gives concrete trigger examples and explicitly says to prefer this tool whenever a name needs to become an ID, which distinguishes it from sibling tools like entity_profile and query.

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 when-to-use guidance through example questions and the directive 'Use FIRST whenever you have a name but need an ID.' It also explains how this tool replaces multiple manual lookups, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds behavioral details: it probes each entity with ai_visibility_check internally, ranks by score, and returns a list with score, confidence, and signal density. This adds value beyond annotations.

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

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

The description is two sentences, front-loading the core purpose and then adding usage context and return format. Every sentence earns its place, and there is no wasted text.

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

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

Without an output schema, the description explains the return format (ranked list with score, confidence, signal density). It covers constraints (2-8 entities, first as subject) and internal mechanism. It is mostly complete, though it could mention error handling for missing API keys.

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

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

Schema coverage is 100% with descriptions for all parameters, so baseline is 3. The description adds semantics: the first entity is treated as 'subject' for narrative, rest are competitors, and clarifies models include 'workers-ai' (default) and 'anthropic' (requires _apiKey). This provides meaningful context beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and identifies which is most/least recognized. It explicitly distinguishes from sibling tools like ai_visibility_check by focusing on multiple entities and a comparative analysis.

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

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

The description specifies usage for competitive AI-marketing audits and implicitly indicates not to use for single entity checks (use ai_visibility_check instead). It provides clear context about when to use, but lacks explicit when-not-to-use or alternative mentions beyond the implied sibling differentiation.

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

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

Beyond the annotations (readOnly, idempotent), the description adds valuable behavioral details: composite fan-out, partial failure handling, bundlephobia delay of 5-30s, and sources_failed reporting. This provides a clear picture of expected behavior.

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

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

The description is concise at 4 sentences, but it is dense with information. It front-loads the composite nature and use case, then details return fields and edge cases. Minor room for structuring but overall effective.

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

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

Despite no output schema, the description thoroughly lists return fields, mentions per-advisory detail and alternative versions, and covers failure modes like timeouts. For a composite tool with multiple data sources, this is complete guidance.

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

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

The schema already has 100% coverage with clear descriptions for both parameters. The description does not add significant new meaning, only restates that scoped packages are accepted, which is already in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools like resolve_entity and scan_competitor_ai_presence by specifying the exact use case.

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

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

Explicitly says to use when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also notes NPM ecosystem only and directs other ecosystems to use deps.dev:version directly, preventing misuse.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the agent knows this is a safe read operation. The description adds contextual details about return fields and the open data portal, but doesn't disclose anything beyond what the annotations imply, such as rate limits or the exhaustive nature of the search. It adds modest value beyond the annotations.

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

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

The description is a single, dense sentence that efficiently communicates the tool's purpose, scope, and output usage. It is front-loaded with the key action and portal name, then provides useful context and downstream 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 read-only search tool with a comprehensive schema and annotations, the description is complete. It provides the source (Toulouse Métropole Open Data), the search basis (by keyword), example themes, and the output fields and their downstream use. Given the absence of an output schema, the description sufficiently covers return values and next steps.

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

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

The input schema has 100% coverage, describing all three parameters (query, limit, offset) with defaults and constraints. The description doesn't add additional parameter-level information beyond what the schema provides, such as the meaning of the query parameter in terms of searching titles/descriptions, which is already in the schema. It aligns with the schema without duplication, but it doesn't compensate for any gaps since there are none.

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

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

The description clearly states the tool's function: searching Toulouse Métropole Open Data datasets by keyword, with specific example themes. It also mentions return values (dataset_ids, titles, themes, record counts) and how to use them (pass to query/dataset_info), distinguishing its purpose from sibling tools.

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

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

The description provides explicit guidance on when to use this tool: searching datasets by keyword, and mentions the context of the open data portal. It also states what to do after searching (pass dataset_ids to query/dataset_info), which clarifies its role relative to sibling tools like dataset_info and query, though it doesn't explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds significant behavioral context: uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation and flag, returns offsets. No contradiction with annotations.

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

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

Description is front-loaded with primary action, then usage context, then technical details. Every sentence adds unique value with no redundancy or fluff. Approximately 6 lines, very 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?

Despite no output schema, description explains return format (passages with offsets and scores) and constraints (cap, truncation). Pairs with sibling tool. Lacks details on error handling or performance, but overall complete for the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds value by providing example queries for the 'query' parameter (e.g., 'supply-chain risk'), which helps the agent understand the format. No extra detail for 'text' or 'limit' beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs ('search', 'pass', 'get back'). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implying it's different from query or recall.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also shows relationship to sibling tool ask_pipeworx_grounded. Does not explicitly state when not to use, but the positive guidance is strong.

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

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

The description goes beyond annotations by detailing OAuth requirement, type-specific parameter schemas, delivery channel constraints (phone verification, 10/day SMS cap, webhook signing and auto-disable), and that the subscription persists. Annotations already indicate write, idempotent, non-destructive nature, and the description adds rich behavioral context 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 appropriately sized for a complex tool with multiple types and delivery options. It is front-loaded with the core purpose and ID, then systematically explains types and delivery. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool's complexity (multiple subscription types, nested params, delivery channels, and no output schema), the description is fully complete. It covers all required parameters, optional settings, prerequisites (OAuth, phone verification), rate limits (10/day SMS), error-tolerance (auto-disable on webhook failure), and the always-on feed channel.

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, but the description adds substantial value by providing concrete examples for each type, explaining the meaning of sub-parameters (e.g., items codes, topics, series IDs), and detailing delivery object constraints (phone format, verification, webhook signing). This far exceeds the schema's bare descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It is specific about the action and resource, and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description provides clear context on when to use this tool (proactive monitoring), requirements (Pipeworx OAuth account, not anonymous), and supported types with example parameters. It implicitly advises against use for anonymous users and mentions that the feed channel is always on, but does not explicitly contrast with alternative tools like 'recent_alerts' for pulling.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns example questions with tool+argument shape, and mentions the response structure. 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 well-structured with a dash-separated list of categories. It's thorough but slightly long; every sentence is useful but could be more concise.

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

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

For a tool with one optional parameter and no output schema, the description is complete: it explains when to use, what it returns (category-bucketed examples), and how to focus with topic. No 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 already provides 100% coverage with description for 'topic' parameter. The description adds practical usage: 'Omit for a cross-category spread' and lists possible values. This 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's the onboarding entry point that returns category-bucketed example questions with exact tool+argument shape. It distinguishes from sibling tools like 'ask_pipeworx' by specifying it's for when you don't know 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 the optional topic parameter to focus. No guidance about when not to use, but that's implied.

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 explains that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds crucial behavioral context beyond annotations, which already indicate non-destructive and idempotent behavior.

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

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

The description is two concise sentences, front-loading the main action and adding essential behavioral details without any 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 single-parameter mutation tool, the description covers the effect (deactivation rather than deletion) and its impact on historical data. No output schema is needed given the simplicity and the context provided.

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

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

The schema already describes the 'id' parameter at 100% coverage. The description adds value by stating the id is returned by subscribe, linking to a sibling tool, which aids correct usage.

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

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

The description clearly states 'Cancel a subscription by id,' providing a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), giving clear context for proper use. It does not explicitly state when not to use or mention alternatives, but the context is strong.

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

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

The description goes well beyond annotations by disclosing the verdict vocabulary (confirmed, refuted, could_not_verify, etc.), distinguishing 'could_not_verify' (check did not happen) from 'unsupported' (no source), and explaining that could_not_verify is not evidence. It also reveals the dual-pipeline mechanics and the citation format. 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 front-loaded with trigger phrases, then progresses logically through purpose, routing, return value, and important caveats. Slightly verbose, but every sentence adds meaningful context for a complex tool. It earns a 4 rather than 5 due to 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?

With no output schema, the description compensates by fully enumerating the return value (verdicts, actual value, citation, reasoning) and clarifying the two special verdicts. It covers what the tool needs (claim) and what callers should know (cannot_not_verify semantics), making it complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'exact percent-delta math' but adds no new parameter-level details beyond what the schema already covers for claim and tolerance_pct. It does not provide additional examples, constraints, or edge-case guidance for the parameters themselves.

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

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

The description opens with natural-language trigger phrases and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by focusing on fact-checking and explicitly stating it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also breaks down routing—structured SEC EDGAR for company-financial claims, grounded pipeline for all other factual claims—giving the agent concrete guidance on how the tool behaves in different contexts.

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