Data Rennes

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive. The description adds that passing _apiKey probes Anthropic with BYO key and cost implications, and clarifies the return 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?

Two concise sentences front-load the primary purpose, followed by key details. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description describes the return structure per model and combined view. For a tool probing multiple LLMs with optional auth, this covers inputs, behavior, and outputs adequately.

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

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

Schema covers all 4 parameters at 100%, and the description adds meaningful context: entity clarification, model options, API key usage, and disambiguation via context. This enriches understanding 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 explicitly states the tool probes LLMs for brand/business visibility and scores it 0-100 per model. It distinguishes from siblings by focusing on AI visibility scoring, which is unique among listed 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 notes it is useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring, which guides typical use cases. However, it does not explicitly state when not to use or provide direct comparisons to 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 cover the read-only, open-world, and idempotent safety profile. The description adds useful behavior beyond that: it fills in arguments, selects the appropriate source tool, and returns a structured answer with stable pipeworx:// citation URIs. It does not detail failure modes or rate limits, but the core execution behavior is disclosed.

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

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

The opening is front-loaded and the examples are useful, but the description becomes messy near the end with garbled fragments like 'default entry point works on every tier', 'Step up only when needed', and '* -news-feeds packs.' Most content earns its place, but the structure is not clean.

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 one-required-parameter tool with no output schema, the description is rich enough: it lists covered domains, gives question examples, states the citation-URI return format, and directs the agent to relevant alternatives. Minor omissions like explicit failure behavior keep it from a 5.

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

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

The schema already fully documents the meaningful parameter: 'question' is described as a natural-language request and its aliases are listed. The tool description adds examples but no new parameter-level semantics, so the baseline 3 applies given 100% schema description coverage.

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

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

The description clearly identifies the tool as a factual-question router: it 'Routes the question to the right one of 5,767 tools across 1506 verified sources' and returns structured answers with citations. It also distinguishes itself from web search and names key sibling alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions.' It also says to step up to ask_pipeworx_grounded for a grounded single answer and to deep_research for broad or multi-part questions, so the agent gets concrete routing rules.

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?

It discloses that candidate routing may be live, that no candidate is currently active, and that the tool currently matches ask_pipeworx exactly. It also clarifies it is a full working router rather than a fallback. These details go beyond the read-only, idempotent, and open-world annotations without contradicting them.

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

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

The description is compact and information-dense, with each sentence covering a distinct aspect: purpose, current state, usage, and fallback behavior. There is minor redundancy between 'identical' and 'currently matches ask_pipeworx exactly', but it does not feel bloated.

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 an output schema, the description compensates by stating that the response shape is identical to ask_pipeworx. It also provides current status, experimental context, and usage guidance. It relies somewhat on knowledge of ask_pipeworx, but that sibling is available and the description gives enough context to make an informed tool-selection decision.

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 all six parameters, with five as aliases for 'question'. The description only adds that the tool takes the same arguments as ask_pipeworx, which reinforces compatibility but does not meaningfully expand the parameter semantics 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable sibling by explaining that candidate routing improvements are enabled live during tests. This gives an agent a specific, actionable understanding of what the tool is and how it differs.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired and that results are compared against the stable router. It does not explicitly state when to avoid it in favor of the stable alternative, but 'beta' and 'experimental edge' strongly imply the intended use context.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the full behavioral flow: selecting from 5,767 tools across 1506 sources, filling arguments, fetching data, and extracting answers only from tool results. It also documents both the success response shape and the explicit refusal reasons, which is especially valuable given there is no output schema. The description does not contradict any annotation.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return contract, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with the key purpose and sibling differentiation, and the length is justified by the absence of an output schema and the need to convey refusal semantics.

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, the description is remarkably complete: it explains what happens under the hood, what success looks like, what refusal looks like, when to use it, and when to use the cheaper sibling. An agent has everything it needs to invoke the tool correctly and interpret its results. No critical operational detail is missing.

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

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

Schema description coverage is 100%, and the question parameter already explains it accepts natural language with aliases such as query, q, prompt, text, and input. The description adds no additional parameter-level semantics, but with full schema coverage the baseline of 3 is appropriate. No compensation is needed.

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

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

The description names a clear, specific purpose: a hallucination-resistant answer mode for high-stakes reads. It explicitly differentiates itself from the sibling ask_pipeworx by describing the same routing but adding grounded extraction from tool results only. The return contract and refusal reasons further clarify what this tool does and does not 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?

The description gives explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted on, and when the agent must not invent facts, with concrete domains like financial verdicts and legal claims. It also states the tradeoff (one extra LLM call) and explicitly directs agents to prefer ask_pipeworx for casual lookups, providing a clear alternative condition.

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 extensively discloses behavioral traits beyond what annotations provide, such as fan-out logic, classifier-specific data sourcing, response shapes (market, analysis, evidence fields), resolver contract (confidence ratings, alternatives), parent event extraction, news fallback behavior, safety short-circuits for low-confidence matches and closed markets, illiquidity warnings, and cancellation rule parsing. It is fully transparent about the tool's behavior and edge cases.

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

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

The description is lengthy but well-structured, using bullet points and paragraph breaks to organize topics like classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, and safety considerations. While every sentence provides value, the length could be reduced by moving some detailed examples to external documentation. However, for a complex tool, the structure is 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?

Given the absence of an output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence) and covers numerous edge cases: low-confidence matches, closed markets, wide spreads, cancellation rules, parent events, and news fallback status. It handles all possible scenarios a user might encounter, making the description very complete for a tool of this complexity.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description adds significant additional meaning: it explains the accepted formats for the 'market' parameter (slug, URL, question text), defines the 'depth' parameter with examples (quick vs thorough), and clarifies the 'include_raw' parameter's purpose and implications for response size. It also provides classifiers and fan-out examples that illustrate parameter usage.

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

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

The description clearly identifies the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies the input types (slug, URL, question text) and the output (evidence packet and market-vs-model comparison). It distinguishes itself from sibling tools like ask_pipeworx and polymarket_edges by focusing on a single bet and integrating multiple data sources.

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

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

The description explicitly states when to use the tool: for questions like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It also covers edge cases (closed markets, low-confidence matches) but does not directly compare with sibling tools or state when not to use it. The guidelines are clear but could be more explicitly differentiated from similar tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable details: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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?

Packs substantial information in a structured way, front-loaded with example queries. Slightly verbose but every sentence adds value. Could be tightened slightly.

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

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

No output schema, but description clearly explains what is returned (paired data + citation URIs). Covers both entity types comprehensively, including data points fetched. Complete 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 adds context: explains 'type' enum values (company vs drug) with detailed data sources, and 'values' format examples (tickers/CIKs for company, drug names). 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 the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with specific examples like 'AAPL vs MSFT'. It distinguishes from sequential lookups and specifies data sources for each entity type.

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

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

Explicitly instructs to prefer this over sequential single-pack lookups when comparing entities, citing efficiency gains. Lacks explicit when-not scenarios but provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds specific behavioral context by listing return types (fields/schema, themes, record count). No contradictions with annotations.

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

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

The description is a single, front-loaded sentence with zero wasted words. It efficiently communicates purpose and usage context.

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

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

Given no output schema, the description lists the specific metadata returned (fields/schema, themes, record count). For a simple, single-parameter tool, this is complete and sufficient for an AI agent to invoke and use correctly.

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

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

The input schema has 100% description coverage for the single required parameter 'dataset_id' with a description referencing search_datasets. The tool description does not add additional parameter meaning beyond what the schema already provides, so baseline score is appropriate.

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

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

The description clearly states the tool retrieves metadata for one Rennes Métropole Open Data dataset, listing specific information (fields/schema, themes, record count). It also provides a usage hint to call before querying to learn column names, distinguishing it from search_datasets.

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

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

The description explicitly advises calling this tool before a query to learn column names, indicating clear usage context. However, it does not explicitly state when not to use it or mention alternatives beyond the implicit sibling tool search_datasets.

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, the description discloses account requirements, paid-tier requirements for 'thorough', the findings packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[]), contradiction scans, semantic excerpting, and expected latency. This substantially enriches the agent's understanding of runtime behavior and side effects.

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 contains a long block of repeated 'For a single lookup use ask_pipeworx instead' sentences, which adds no information and seriously bloats the text. While the opening content is dense and front-loaded, the repetition makes the description poorly structured and wastes tokens.

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

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

For a complex research tool with no output schema, the description is remarkably complete: it covers auth, tiers, supported data sources, decomposition approach, output format, gap and contradiction handling, citation resolvability, and latency. Nothing critical is missing for an agent to decide whether and how 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?

The schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful operational detail: the 'thorough' depth is paid, quick=3/standard=3/thorough=6 facets, single-hop vs gap-recovery hop behavior, and latency implications. That goes beyond the schema without being redundant.

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

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

The description uses a specific verb and resource: grounded multi-source research across 1506 structured data sources, highlighting that it is NOT open-web search. It also explicitly contrasts with ask_pipeworx for single lookups, making the tool's purpose and differentiation clear.

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 states when to use the tool ('best for broad/multi-part questions over structured data'), when not to use it ('for a single lookup use ask_pipeworx instead'), and even provides auth-tier guidance ('if you are not signed in, use ask_pipeworx instead'). This is explicit usage guidance with named alternatives.

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

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

Annotations indicate read-only and idempotent behavior. The description adds value by explaining the return format (names, descriptions, schemas with examples) and that results are 'ready to call directly.' It also notes the various alias parameters. 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 clear front-loaded purpose. Every sentence adds value: purpose, usage guidance, return details, and a call to action. It is slightly long but justified given the content.

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

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

Despite no output schema, the description fully explains what the tool returns (names, descriptions, schemas with examples) and how to use it. It covers the parameter aliases and use cases. For a simple discovery tool, this is complete.

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

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

Schema coverage is 100% with descriptions for each property. The description reinforces this by listing aliases (task, q, search, description) and providing examples for the query parameter. It also explains the limit parameter's default and max. This adds context 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: 'Find tools by describing the data or task.' It provides specific examples of search domains (SEC filings, financials, etc.) and explains what it returns (top-N tools with full schemas). This distinguishes it clearly from sibling tools that query data directly.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' While it doesn't explicitly state when not to use it, the context of sibling tools implies alternatives exist for specific queries.

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

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

Adds substantial behavior beyond the readOnly/openWorld/idempotent annotations: multi-source parallel fan-out with a GDELT→GNews fallback, USPTO soft-fail behavior ('soft-fails until reactivated'), expected-empty semantics ('a company with only small-molecule/generic drugs will show none here, that is expected, not a failure'), and the sources_used/sources_failed contract distinguishing real absence from bugs. 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?

Front-loaded with intent and every clause carries meaning, but the description is a single dense unbroken wall of text with deep nested parentheticals (e.g., the patents sunset aside and the fda_products explanation). It restates input-format information already fully covered by the schema, and would benefit from bulleted sections given its length.

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

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

Despite having no output schema, the description enumerates all return sections (cik, company_name, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed), all accepted input forms, and edge-case outcomes (private company, empty sections, soft-fails). An agent has everything needed to invoke it correctly for a complex multi-source 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% and the schema already documents that type accepts 'company' or 'ticker' interchangeably and that value takes a ticker, zero-padded CIK, or company name. The description reinforces this and adds the resolved_from/resolved_to and private-company resolved:false edge cases, which is helpful but does not substantially exceed what the schema already conveys.

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

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

States a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' backed by example user phrasings. It distinguishes itself from alternatives by enumerating the exact sources it fans out across (SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL, GDELT/GNews, GLEIF) and explicitly says to prefer it over chained single-pack lookups.

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

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

Gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is clear when-to-use guidance. It does not, however, name sibling tools like compare_entities or resolve_entity as alternatives, nor state explicit when-not-to-use conditions beyond the implicit private-company case.

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

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

Description confirms destructive nature ('delete', 'clear sensitive data'), matching annotations (destructiveHint=true). Adds context on data type and usage scenarios 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, no filler, all information is relevant. Highly concise.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and pairing sufficiently.

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 schema already describes the 'key' parameter. Description adds no extra detail beyond usage context, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb+resource. It distinguishes from sibling tools remember and recall by mentioning pairing.

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

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

Explicit use cases given: stale context, task done, clearing sensitive data. No explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is low. The description adds value by explaining the extraction process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown). It does not discuss error handling or rate limits, but the annotated behavioral traits are well-addressed.

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 plus a concise list of use cases. It is front-loaded with the main action and output, with no unnecessary words. Every sentence adds value, making it efficient for an agent to parse.

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

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

Given two simple parameters and no output schema, the description adequately covers the tool's behavior and output. It explains the generation steps and the expected markdown format. Missing details like error handling or URL validation, but the tool is straightforward and the description is sufficient for typical usage.

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

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

Schema description coverage is 100%, placing the baseline at 3. The description adds minimal extra meaning beyond the schema: it confirms max_links is for link entries but does not explain constraints or edge cases. The tool description does not significantly compensate for the already informative 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 generates a production-ready llms.txt file for a URL, specifying the output format and purpose for AI crawlers. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning presence.

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

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

The description provides explicit use cases (client indexing, drafting, auditing competitors), but does not mention when NOT to use the tool or direct alternatives among sibling tools. The context is clear enough for most agents, but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true, indicating safe read operations. The description adds value by listing the specific fields returned (id, type, params, etc.) and frames it as a review activity, which complements the annotations without contradiction.

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

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

Two sentences efficiently convey purpose, return fields, and usage guidance. Every sentence adds value, and the structure is front-loaded with the core action.

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

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

Given the simple input (one optional parameter) and annotations indicating safe read, the description adequately covers what the tool does, returns, and when to use it. No output schema exists, but the description lists the return fields, so it is complete enough.

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 schema already documents the optional include_inactive parameter. The description does not add further meaning to the parameter beyond the schema's definition, so it meets 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 clearly states the tool lists the caller's active subscriptions, specifying the verb 'List' and resource 'subscriptions,' and differentiates from siblings like subscribe/unsubscribe by focusing on listing. The sibling list includes subscribe and unsubscribe, so the purpose is distinct.

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

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

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

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

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

The description goes far beyond annotations by disclosing rate limits (5 per identifier per day), free usage, the anonymous claim_token flow, how to check resolution status, and that the team reads digests daily. Annotations are all false, so there is no contradiction, and the description adds substantial 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?

Every sentence earns its place: purpose, categories, exclusion, token mechanics, rate limit, and cost. The description is front-loaded with the core action and structured logically, making it long but information-dense with no 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?

The tool has no output schema, but the description fully explains the return value (claim_token), how to use it, and the overall workflow. It also covers constraints (only Pipeworx tools, rate limit, free), making the description complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds extra value by explaining the claim_token lifecycle (filing without an account returns a token; passing it later retrieves status) and reinforcing message quality ('be specific'). This exceeds the baseline 3 for full schema coverage.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about something broken, missing, or working well. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and it distinguishes itself from sibling tools by focusing solely on feedback, whereas siblings are research and query 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?

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and an explicit when-not-to-use exclusion (tools from other MCP servers, with direction to file elsewhere). It also offers practical guidance on what to include ('describe in terms of Pipeworx tools/packs') and what to avoid ('don't paste the end-user's prompt').

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

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

Annotations already declare readOnly, idempotent, nondestructive. Description adds data source (CF analytics-engine), caching behavior, and privacy (no PII), providing valuable 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?

Four sentences, front-loaded with purpose, no fluff. Every sentence adds value, including use cases and behavioral notes.

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

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

Given one parameter, full schema coverage, and annotations present, the description covers return values, data source, caching, and privacy sufficiently.

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

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

Only one parameter with full schema coverage and description. The description adds context on window selection, enhancing understanding beyond the enum labels.

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

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

The description clearly states it returns trending tools, packs, and call volume over a window. It uses specific verbs and distinguishes itself from sibling tools by focusing on aggregated trending data from other AI agents.

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?

Lists three explicit use cases and provides guidance on window selection (shorter for hot, longer for steady-state). Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: scanning algorithm, semantic anchor (Jaccard ≥0.30), partition filter (placeholder check), fill check logic, and 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 long (~400 words) but well-structured with clear sections for each mode, algorithms, and examples. Front-loaded with purpose and modes. Some redundancy (e.g., repeat of fill check details) could be trimmed, but overall efficient for the complexity.

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

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

With no output schema, the description fully explains the response format (opportunities array with fields, partition_check object in event mode) and the fill check process. It even references sibling tool for custom sizing, ensuring the agent knows 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?

Schema coverage is 100%, and the description adds deep context: explains event slug format with examples, topic as seed question, and how each mode affects the scan. This goes far beyond the schema's brief 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's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Provides recommended use cases and warns when not to trade (e.g., if realizable_edge_pp <= 0).

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: details three model families with formulas, explains edge_pp_net (after slippage), kelly_fraction caps, 24h-move warning, caching at KV level, and function of diagnostic fields. 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 lengthy but well-structured with clear sections for model families and knobs. It front-loads purpose and quickly gets to details. Every sentence provides useful information, though some could be shortened.

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 9 parameters (100% schema coverage) and no output schema, the description fully compensates by detailing the response structure (by_segment, fed_candidates, _diagnostics), caching behavior, and how filters affect output. It leaves no ambiguity about what the tool returns.

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

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

Schema coverage is 100% with good per-parameter descriptions. The tool description adds extra value by explaining the interaction of parameters like min_partition_leg_kelly with partition arbs, the practical effect of slippage_pp, and tradeable-edge filter rationale. This goes beyond the schema.

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

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

The description states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-driven edge detection.

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 frames the tool as 'what should I bet on today' and explains when to use knobs like min_liquidity and max_spread_pp. It also notes that Fed bets are excluded from ranking. While it doesn't contrast directly with all siblings, the usage context is very clear.

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds significant context: it reads daily snapshots, returns tracked/expired/snapshot_dates, explains limits (60-day TTL, decay from daily closes), and clarifies no destructive actions. 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 concise yet comprehensive, front-loading the core purpose and then detailing response fields and limitations. 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?

Despite no output schema, the description thoroughly explains all return fields (tracked, expired, snapshot_dates) and limitations. Given the tool's complexity (time-series of edges), it provides complete context for an agent to use it correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats the defaults and adds a max of 30 days (consistent with schema's clamp). It does not provide new insight beyond the schema for the input parameters, but it does describe the output structure, which is not in schema. Baseline 3 is appropriate.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge existed and whether it's shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current snapshot data.

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

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

The description gives a concrete scenario: comparing a fresh wide edge to a 3-week-old wide edge, implying when to use this tool for historical context. It does not explicitly state when not to use it, but the purpose is clear enough to infer 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, destructiveHint false. Description adds context: walks the ladder for single-market, checks every leg for basket, warns about thin legs and forced directional risk. No contradiction, and 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?

While long, the description is well-structured with labeled sections (REQUIRES, SINGLE-MARKET, BASKET) and every sentence provides essential information. Slight length reduction possible but not detrimental.

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

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

For a complex tool with two modes and no output schema, the description thoroughly covers return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), edge cases (thin legs, forced directional risk), and practical implications. Complete enough for correct agent invocation.

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

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

Schema covers 100% of parameters. Description adds meaning: explains single-market vs basket modes, default side for basket (auto from partition sum), and clarifies size_usd interpretation for basket as settlement notional (shares per leg).

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

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

The description clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth for single-market or basket modes. It distinguishes from siblings by specifying when to use it before polymarket_arbitrage or polymarket_edges trades, and provides the verb 'check' with resource 'edge'.

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

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

Explicitly states when to use: before acting on arb signals or edges trades above ~$500. Explains consequences of not using it (partial basket fills convert arb into unhedged directional position). Clearly states requirement for one of 'market' or 'event'.

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

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

With readOnly/openWorld/idempotent annotations already in place, the description still adds substantial behavioral context: compatibility warnings and codes, both potentially non-empty on returned pairs, pairing_unverified semantics, temporal alignment null semantics, fee-schedule non-modeling, unclassified leg handling, and skipped comparison counters. It goes far beyond the annotations without contradicting them.

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

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

The description is long but genuinely dense with necessary information, and it is front-loaded with the core purpose before diving into modes, response fields, safety codes, and caveats. Section labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes make the structure navigable, and nearly every sentence adds operational value.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains the response shape, edge-case behavior, safety fields and codes, fee disclaimer, temporal alignment semantics, and skipped-leg accounting, leaving an agent with enough context to invoke the tool correctly and interpret its output.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that the explicit ticker/slug parameters override the topic-mapped side and that both modes run the same token-overlap matcher. It also clarifies that all three parameters are optional and how combinations select the comparison 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 opens with a specific statement of what the tool computes: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly identifies the resource and operation, and it differentiates itself from related tools by focusing on cross-venue spread and explicitly defining the two supported modes.

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 tool clearly explains when to use each mode: pre-mapped `topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings. It also warns that most pre-mapped topics return compatibility warnings and are not necessarily tradeable. However, it does not name or contrast itself with sibling tools like `polymarket_arbitrage`, so alternative-selection guidance is incomplete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's mention of 'Query' and 'ODSQL' aligns with these annotations but adds minimal additional behavioral context beyond what is already conveyed by 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, front-loaded sentence that immediately conveys the tool's purpose and lists its core operations without any fluff. Every word adds value.

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

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

The description fully explains the tool's functionality given the rich schema and annotations, but it omits the output format (e.g., JSON). Since there is no output schema, mentioning the return type would improve completeness.

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

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

Schema description coverage is 100%, so the schema itself documents each parameter. The description provides a high-level overview of parameter roles (e.g., 'Filter (where)') but does not add detailed syntax or constraints beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Query' and the resource 'records from a Rennes Métropole Open Data dataset', and specifies the query language (ODSQL). It lists core operations (filter, aggregate, sort, paginate) which distinguishes it from sibling tools like search_datasets (which finds datasets) and search_within.

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 when to use the tool: to query records with ODSQL capabilities. However, it does not explicitly mention when to avoid this tool or suggest alternative sibling tools for different use cases, slightly reducing the score.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral context: retrieving saved values, scoping per identifier, and the ability to list all keys. No contradictions.

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

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

The description is extremely concise: three sentences that front-load the core action, then provide use cases and context. Every sentence adds value with no redundancy or filler.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, scoping, and pairing with sibling tools. It is complete enough given the low complexity and supporting annotations.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description reinforces this by explaining that omitting the key lists all saved keys, and adds context about the memory system ('previously saved via remember'). This enhances understanding beyond the schema.

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

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

The description clearly states the tool's primary function: retrieve a specific value by key or list all keys. It uses specific verbs ('retrieve', 'list') and resources ('value', 'keys'), and references sibling tools ('remember', 'forget') to differentiate.

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 guidance on when to use the tool ('look up context the agent stored earlier') and scoping ('scoped to your identifier'). It implicitly suggests alternatives by mentioning 'remember' and 'forget', but does not explicitly state when not to use it.

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

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

Description adds behavioral context beyond annotations: it explains that mark_read flags events as read to control what appears in subsequent calls, and that the feed is persisted. Annotations confirm readOnly, idempotent, and non-destructive, with no contradiction.

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

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

The description is a single paragraph of five sentences, each adding distinct value: purpose, returned fields, filtering, mark_read behavior, and alternative access. No superfluous words, front-loaded with key action.

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

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

Given 5 optional parameters and no output schema, the description adequately covers what the tool returns (three fields), how to filter, and pagination via mark_read and unread_only. It also mentions polling is fine and an alternative endpoint. Missing some details on output structure but sufficient for a read 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?

With 100% schema description coverage, baseline is 3, but the description adds value: it provides an example for type ('sec_8k'), explains that mark_read causes read flagging for next calls, and clarifies max events range. This goes beyond the schema descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts with details on fields like source, citation_uri, and raw payload. It distinguishes itself from sibling tools by specifying it's for the subscription feed, and provides filtering options.

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 that polling works fine and provides an alternative URL for scripts/dashboards, implying this tool is for interactive use. However, it lacks explicit when-to-use versus alternatives like list_subscriptions or subscribe, and does not mention when not to use it.

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

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

Rich behavioral detail beyond annotations: data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with sunset note), grouping of results, return structure including citations. Annotations already confirm read-only and idempotent; description adds non-redundant 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?

Packed with information in a single paragraph. Could be slightly more structured (e.g., bullet points for sources), but not overly verbose. 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?

Very complete given tool complexity. Covers all data sources, fallback behavior, date parsing, and return structure. No output schema, but description adequately describes return format. Addresses potential confusion points (e.g., PatentsView sunset).

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

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

Schema coverage 100% with descriptions for all parameters. Description adds examples for 'since' (ISO vs relative), clarifies 'value' accepts ticker or CIK, and notes 'type' is restricted to 'company'. Complements schema well.

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

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

Description clearly states the tool provides a change feed for a company, covering SEC filings, news, and patents. Uses specific verbs like 'fans out' and gives example queries. Distinguishes from sibling entity_profile.

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

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

Explicitly tells when to use entity_profile instead for static profile. Provides concrete examples of queries and date formats. No ambiguity about when this tool is appropriate.

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

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

Discloses scope (identifier), persistence (auth vs anonymous 24h), and key-value nature. Adds value beyond annotations (readOnlyHint false, idempotentHint true, destructiveHint false) 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?

Four sentences, each purposeful: what, when, how, and pairing. No wasted words, front-loaded with action verb.

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

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

Covers all necessary aspects for a simple key-value store: purpose, usage, behavioral details, and sibling interactions. No gaps given 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% with descriptions; description adds practical examples for key naming (e.g., subject_property) and clarifies possible values, enhancing usability.

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

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

Clearly states the tool saves data for reuse, specifying verb (save), resource (data), and context (across sessions). Distinguishes from siblings by mentioning recall and forget.

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

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

Provides explicit when-to-use guidance with examples (ticker, address, preference). Lacks explicit when-not-to-use or alternatives, but pairs with recall/forget effectively.

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 the tool read-only and idempotent, and the description adds substantial behavioral detail: graceful degradation when LEI/FIGI enrichment fails, ambiguity handling via figi_candidates, explicit unresolved identifiers, source-labelled results, and internal cascading across lookup endpoints. No statement contradicts the annotations.

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

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

The description is long but well-structured: example phrasings first, then type-specific details and explicit caveats, then fallback behavior. A few phrases are somewhat redundant, such as 'which is the correct answer to an issuer name that does not identify a single bond' and 'replaces 2-3 manual lookups,' yet the density of useful information earns the 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?

There is no output schema, so the description compensates by explaining what callers receive: canonical identifiers with source labels, unresolved fields, figi_candidates, drug RxCUI citations, and degradation behavior. For a complex multi-endpoint resolver, this is complete enough for an agent to invoke it correctly and interpret results.

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

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

The schema already describes both parameters at 100% coverage, but the description goes well beyond it with examples, exact formatting requirements, the bond issuer only rule, trailing-word caveats, and ISIN-to-LEI resolution semantics. This materially helps an agent construct correct parameter values.

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

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

The description states a precise verb+resource: resolving user-spoken names to canonical/official identifiers, with concrete example phrasings and two supported entity types. It clearly differentiates the tool's role from generic query or profile tools by positioning it as the identifier-lookup layer 'other tools require as input'.

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

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

It gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID,' along with natural-language example queries and supported types. However, it does not name specific sibling tools to avoid or state explicit when-not-to-use conditions, so it falls just short of full alternative routing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: probes each entity, ranks by score, returns a list with score/confidence/signal density, no contradictions.

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

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

Three sentences, each earning its place: purpose, mechanism, use case with return info. Front-loaded with the core action.

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

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

Given no output schema, the description explains return format. It covers inputs well but doesn't address constraints like minimum entity count (schema says 2-8). Overall complete for a comparative 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 the description adds meaning: notes first entity is subject, explains model defaults ('Omit for just workers-ai'), and clarifies _apiKey usage.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses specific verbs like 'compare', 'probes', 'ranks', and distinguishes itself from siblings like single-entity ai_visibility_check.

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 frames it for competitive AI-marketing audits and gives an example query. It implies when to use but does not provide explicit when-not-to-use or list alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral context: fans out to external services, first measurement may take 5-30s, partial failures are reported via sources_failed. 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?

Concise yet information-dense; each sentence adds value. Front-loaded with purpose, followed by details on sources, return data, failure handling, and usage scope. No wasted words.

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

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

No output schema exists, but the description fully describes the return structure (summary block with specific fields, per-advisory details, links, alternative versions). Also covers failure modes and timeouts, making the tool's behavior 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 clear descriptions. The description confirms that scoped packages are accepted and version defaults to latest, but this adds minimal additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, version history, bundle size, dependency count, ESM/tree-shake support. It distinguishes from sibling tools by specifying the npm ecosystem and the combined external sources (deps.dev + bundlephobia).

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 ('is X safe / popular / small?' or 'what does adding lodash cost me?') and when not to (other ecosystems like PyPI/Maven fall under a different tool). Also mentions graceful degradation and timeout behavior, guiding the agent on expected outcomes.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar for transparency is lower. The description adds useful context: it returns dataset_ids and indicates a two-step process (pass to query/dataset_info). It also mentions the thematic scope. No contradictions. This is decent behavioral 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?

Two sentences, front-loaded with the core action, no filler. Every clause adds value: the scope, the return fields, and the linkage to other tools. Perfectly concise and structured for quick absorption.

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

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

Given three simple parameters, rich annotations, and no output schema, the description covers the essentials: what it searches, what it returns, and how the output is used. It doesn't detail pagination or rate limits, but the schema and annotations cover those. The linkage to query/dataset_info enhances completeness. A small gap: it doesn't explicitly say the search is case-insensitive or language-specific, but that's not critical.

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

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

Schema description coverage is 100% for all three parameters (query, limit, offset). The description doesn't materially add to parameter semantics beyond what the schema provides, though it does mention 'keyword' which aligns with query. It adds a hint about domains but no new syntax or format details. The baseline for high coverage is 3, and the description neither improves nor worsens it.

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

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

The description clearly states the tool's function: 'Search Rennes Métropole Open Data for datasets by keyword' with specific categories (mobility, urban services, environment & geography). It also lists the return elements (dataset_ids, titles, themes, record counts), differentiating it from siblings like dataset_info (which likely retrieves details by ID) and query (which might execute data queries). This verb+resource+scope is precise and distinct.

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

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

The description implies when to use it: to find datasets before calling query/dataset_info, explicitly stating 'Returns dataset_ids (pass to query/dataset_info)'. This provides a workflow hint. However, it doesn't explicitly exclude other search tools or state 'use when you need to discover datasets', but the linkage is strong enough. It's clear and contextual.

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 rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds technical details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), truncation behavior, and that passages carry offsets for verification.

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?

Concise single paragraph that front-loads the core function, followed by use case and technical details. Every sentence adds value with no redundancy.

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

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

Given the tool complexity, the description fully covers purpose, usage, technical behavior, limitations, and relationships to siblings. No output schema, but return values are well described (top-N passages with offsets and scores).

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

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

Schema coverage is 100%, and the description adds meaning: explains the text parameter purpose and limit, provides query examples ('supply-chain risk', 'fiscal year 2024 revenue'), and specifies limit range and default. This adds 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 it performs semantic search inside a fetched record, using a specific verb and resource. It differentiates from siblings by mentioning its pairing with ask_pipeworx_grounded and the ability to return passages with offsets.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It provides context on alternatives, such as grounding over relevant passages instead of the whole document, and mentions a complementary tool (ask_pipeworx_grounded).

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 non-read-only, non-destructive, idempotent behavior. The description adds behavioral context: requires authentication, returns subscription id, delivery constraints (phone verification, 10/day cap, webhook signing secret), and that subscriptions persist. 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 reasonably concise, front-loading the purpose and key requirements. It covers necessary details without excessive verbosity, though it could be slightly more compact.

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

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

Despite no output schema, the description explains the return value (subscription id) and covers all important aspects: prerequisites, type-specific parameters, delivery options, and limitations. It is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for each type and clarifies delivery constraints (e.g., phone must match verified phone, webhook secret returned once), which adds meaning beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb+resource pair. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool: for creating subscriptions to specific event types. It mentions prerequisites (Pipeworx OAuth account) and lists supported types with examples. However, it does not explicitly state when not to use it or directly compare to siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds details: returns category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog. No contradictions.

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

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

The description is front-loaded with trigger phrases and well-structured, but slightly verbose with multiple rephrasings of the same intent ('what can I ask...', 'give me ideas'). Still earns its length.

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

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

No output schema exists, but the description fully explains the return format (category-bucketed examples with tool+argument shape). Provides enough context for an agent to understand the value and usage.

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

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

With 100% schema coverage, the description adds significant meaning: call with no arguments for full spread, or pass a topic (e.g., 'finance') to focus. It also lists example topic values, beyond the schema's generic description.

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

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

The description clearly states it is the onboarding entry point for Pipeworx, returning category-bucketed example questions. It distinguishes from siblings like ask_pipeworx by being the first tool to use when unsure of capabilities.

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 instructs to use this tool FIRST when you don't know what Pipeworx can do, and mentions alternatives (meta-tools). The optional topic parameter usage is clearly explained.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts. Adds context beyond annotations which only hint at non-destructive modification.

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, no wasted words. Every sentence adds value.

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

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

Simple tool with one parameter and full annotations; description covers ownership, behavioral effect, and historical data retention sufficiently.

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

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

Schema coverage is 100%; description does not add extra meaning beyond the schema's parameter description. Baseline 3 is appropriate.

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

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

Clearly states the action (cancel) and resource (subscription by id). Distinguishes from siblings like subscribe and list_subscriptions.

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

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

States ownership enforcement: only cancel own subscriptions. Provides clear usage context but does not explicitly mention when not to use or name alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive, but the description adds crucial behavioral context: it explains the verdict taxonomy, distinguishes between could_not_verify and unsupported with a warning that the former must not be treated as evidence, and discloses the internal two-path routing (structured SEC path vs. grounded pipeline). The verification_error{stage,detail} detail further exposes failure modes. 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 but appropriately detailed for a tool with multiple routing paths and nuanced result semantics. It front-loads trigger phrases and purpose, then handles edge cases and warnings. While a bit long, every sentence adds value—especially the caller-important warning about could_not_verify. It earns a 4 rather than 5 because the traffic of examples and multiple clauses could be tightened without losing meaning.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete: it specifies return values (verdict categories, actual value, citation, reasoning), explains failure states, gives concrete examples for financial and non-financial claims, and indicates the tool replaces multiple sequential calls. This gives an agent everything needed to select and invoke the tool appropriately.

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

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

The input schema covers 100% of parameters with rich descriptions, so the baseline is 3. The main description does not add additional parameter semantics beyond the schema; it focuses on usage and return values. The schema itself already explains tolerance_pct overrides and hallucination-detection usage, so the description does not need to compensate, but it also doesn't elevate 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 opens with concrete trigger phrases ("Is it true that…", "fact check", "verify the claim that…") and immediately defines the tool as "natural-language claim verification against authoritative sources." It clearly distinguishes itself from general-purpose siblings like ask_pipeworx or deep_research by focusing on claims requiring a verdict, and further differentiates between company-financial verification (SEC EDGAR/XBRL) and any other factual claim via a grounded pipeline.

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 given: "Use whenever the agent needs to check whether something a user said is factually correct." It also details routing rules for company-financial vs. other claims, clarifies when a result means the check did not happen (could_not_verify) versus unsupported, and notes that this tool replaces 4–6 sequential calls, directly positioning it as the preferred single-call alternative.

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