Data Sncf

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds behavioral details: default model, BYO key for Anthropic, output structure (per-model scores, combined view). 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?

Four sentences, front-loaded with purpose, no fluff. Each sentence adds essential information. Well-structured and easy to parse.

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

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

For a 4-parameter tool without output schema, the description covers what it returns (per-model score/confidence/signals/raw_response + combined view) and model options. Missing some specifics on output format, but adequate for selection.

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

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

Schema coverage is 100% with descriptions. The description adds value by specifying default model, supported models, and that _apiKey is passed directly to Anthropic. It enriches the schema without just repeating.

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

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

The description clearly states it probes LLMs for visibility of an entity and returns a score. It specifies verb 'probe' and resource 'visibility'. While it doesn't explicitly distinguish from siblings like 'scan_competitor_ai_presence', the unique scoring and per-model detail make it 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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use the free default model vs requiring an API key for Anthropic. However, it doesn't explicitly say when not to use it or compare 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?

Given annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description goes beyond these by explaining that the tool routes to the right internal tool, fills arguments, and returns an answer with pipeworx:// citation URIs. This is useful behavioral context, especially since there is no output schema. It does not mention potential latency or failure modes, but the core behavior is transparent.

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

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

The description is front-loaded with a key usage directive and includes a useful list of domains and examples. Some repetition exists ('PREFER OVER WEB SEARCH' appears at both start and end), but every section contributes to the agent's decision-making.

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 is largely complete for a tool of this complexity: it explains what it does, when to use it, what it returns, and gives examples. Since there is no output schema, the mention of structured answers and citation URIs is valuable. It does not cover every possible edge case, but is sufficient for correct selection and 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?

The input schema covers all six parameters and describes them as aliases for a single natural-language question, so the schema already provides strong coverage. The description adds meaningful semantics by specifying the types of factual questions to ask and providing examples, which helps the agent understand what input 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 that ask_pipeworx routes natural-language questions to one of thousands of tools across verified sources and returns structured answers with citation URIs. It is specific about the resource and function. However, it does not distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it falls short of full sibling differentiation.

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

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

The description provides explicit when-to-use guidance, including a strong directive to prefer it over web search, a detailed list of domains, and concrete example queries. It gives clear context and even says 'START HERE for most questions.' However, it does not provide explicit when-not-to-use guidance or compare itself to sibling ask_pipeworx variants.

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?

Given annotations already mark it read-only, idempotent, and non-destructive, the description adds useful behavior beyond those: experimental routing candidates may be live, no candidate is currently active, and the tool is a full working router rather than a wrapper with fallback. The 'Falls back to nothing' line is slightly ambiguous but is immediately clarified to mean 'not a fallback'.

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 sentence is information-dense and front-loaded, and the candidate-state and usage guidance are relevant. It is slightly longer than necessary and the final sentence partly repeats already-established behavior, introducing mild ambiguity ('Falls back to nothing').

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 one-required-argument router, the description covers what it is, current candidate state, how to choose it, and the lack of a fallback. It omits an actual description of the response content, but it explicitly says the response shape is identical to ask_pipeworx, transferring that knowledge to a known sibling; no output schema exists to fill the gap.

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 every parameter already documents its role as an alias for question, which is enough for an agent to invoke the tool. The description only repeats that arguments are identical to ask_pipeworx and adds no additional parameter guidance.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,714 tools, arguments, and response shape, so an agent can tell what it does and how it differs from the stable tool. It is not a 5 because it never plainly defines what ask_pipeworx itself answers or routes, relying on the name and schema for that meaning.

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

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

It explicitly names the stable alternative (ask_pipeworx), gives the condition for choosing this beta ('when you want the newest routing'), and states that results are compared against the stable router to decide what merges. It does not state an explicit 'do not use in production' exclusion, but the experimental-vs-stable framing 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?

Goes well beyond the annotations by disclosing the extra LLM call cost, the strict evidence-only extraction rule, the exact success return shape, and the refusal contract with specific refusal reasons. The description adds rich behavioral context and 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 efficient and front-loads purpose, then moves through return contract, usage criteria, and cost trade-off. Every sentence serves a distinct decision-relevant purpose, and there is no filler or repetition.

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

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

Because there is no optional but well-developed output schema, the description compensates by spelling out both success and refusal response shapes. Combined with full schema param coverage and the explicit cost/usage trade-off, the agent has everything needed 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 description coverage is 100%, so the parameters are already fully documented and the description does not need to explain them. The description references internal argument filling but adds no parameter-specific meaning beyond what the input schema provides, matching the baseline.

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

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

The description explicitly defines the tool as a hallucination-resistant answer mode for high-stakes reads, with concrete behavior: it routes like ask_pipeworx, fetches from a tool result, and extracts answers only from that content. This clearly distinguishes it from the base ask_pipeworx tool and other siblings.

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: whenever an answer will be quoted, cited, or acted on, and in domains where invented facts are unacceptable (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative ask_pipeworx and says to prefer it for casual lookups, giving clear when-not-to-use direction.

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, open-world, non-destructive behavior. The description adds extensive behavioral context: market resolution, classification, fan-out to multiple sources, edge cases like low-confidence matches, closed markets, wide spreads, cancellation rules, news fallback mechanisms, and response shapes. 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 comprehensive but excessively long, covering many scenarios and edge cases in dense detail. It is well-structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), but the verbosity may hinder quick comprehension. Could be more streamlined while retaining key points.

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

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

Given the tool's complexity (multiple classifiers, source fan-outs, response shapes, error handling), the description is extremely complete. It addresses market match confidence, parent events, news fallback, safety measures, wide spread tradeability, cancellation rules, and more. No output schema, but return values are thoroughly explained.

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

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

All three parameters have schema descriptions, achieving 100% coverage. The description goes well beyond schema by detailing the market parameter valid forms (slug, URL, question text), depth options, and include_raw effects. Examples and notes significantly enhance understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It defines inputs (slug, URL, or question text) and outputs (evidence packet + comparison). It distinguishes itself from sibling tools by focusing on Polymarket and Pipeworx data integration.

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

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

Explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not directly compare to siblings like polymarket_edges, the context implies it is the go-to for initial research. Lacks explicit 'when not to use' but provides clear intent.

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. The description adds details: uses latest 10-K data, handles off-calendar fiscal years, returns sorted results and 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?

Front-loaded with query examples, each sentence adds value. Slightly long but justified given the information density. Could be slightly trimmed without loss.

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

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

No output schema, so description explains it 'Returns paired data + pipeworx:// citation URIs per entity.' Covers data sources, sorting, and typical use cases. While exact output structure is vague, it is adequate for the tool's role.

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

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

Schema coverage is 100% but description adds significant meaning: explains what each type returns, acceptable value formats (tickers vs drug names), min/max items, and sort behavior. Goes well beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with concrete query examples. It distinguishes from sequential single-entity lookups, implying it replaces multiple calls to entity_profile or similar 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?

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides context on data sources per type but does not explicitly list sibling tools to avoid.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specifics about return contents (fields/schema, themes, record count) and the pre-query role, which enriches transparency without contradiction.

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

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

Single sentence, 15 words, front-loaded with core action. No redundancy or extra content. Every word earns its place.

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

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

With one parameter, rich annotations, and no output schema, the description sufficiently covers purpose, behavior, and usage. It could briefly mention example return format but is otherwise complete.

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

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

Schema_description_coverage is 100%, with the parameter dataset_id already documented. The description adds minor context ('Dataset id from search_datasets') but does not significantly extend schema meaning, warranting the baseline score 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 it retrieves metadata (fields/schema, themes, record count) for one SNCF Open Data dataset. It distinguishes from siblings like search_datasets and query by specifying it's a pre-query step.

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 'call before query to learn the column names,' providing clear usage context. It doesn't explicitly state when not to use or list alternatives, but the guidance is strong enough for correct invocation.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses a lot of behavior: parallel decomposition routing to 5,714 tools, the findings packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), explicit gaps[] for unanswered facets, never-invented policy, semantic excerpting (not head-truncated), contradictions[] for standard/thorough, and expected latency ranges per depth. The caveat about citation_uri being present only when fetchable is especially transparent. No contradictions with annotations.

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

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

The description is long, but nearly every sentence earns its place by conveying operational behavior, constraints, and caveats that an agent needs for correct invocation. It is front-loaded with the most critical fact (account requirement and fallback). The main cost is the informal all-lowercase stylistic flourishes ('gaps[]', 'never invented'), which add personality but slightly reduce scannability. Given the complexity of the tool, the length is justifiable.

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 well-documented parameters, no output schema, and rich annotations, the description covers the essential call conditions (auth, paid tier, fallback tool), expected latency, output format, edge-case behavior (unanswerable gaps, unresolvable citations), and the difference between depth levels. An agent has everything needed 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?

The schema already documents both parameters fully (100% coverage), including the depth enum semantics. The description adds value by explaining what the depth values mean in terms of hops and contradiction passes and by elaborating that question can be broad/multi-part because decomposition is the point. This goes beyond the schema, though the schema itself did the heavy lifting — hence a 4 rather than 5.

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 'Grounded multi-source research across Pipeworx's 1495 STRUCTURED data sources... in ONE call' and explicitly contrasts with open-web search. The verb 'research' plus the resource (structured Pipeworx data sources) and the distinguishing scope ('broad/multi-part questions over structured data') clearly identify the tool's purpose. It even names the sibling 'ask_pipeworx' for single-lookup cases, so it is well differentiated.

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

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

The first line gives an explicit account requirement and tells the agent to use ask_pipeworx instead when signed out. It then specifies when to use deep_research ('Best for broad/multi-part questions over structured data') and contrasts with 'For a single lookup use ask_pipeworx instead' — explicit when/when-not guidance plus named alternative.

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

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

Annotations already indicate safe, read-only operation. The description adds valuable context: returns full input schemas with examples, ready to call directly. No contradictions.

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

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

Description is long with an extensive list of domains and examples. While front-loaded with purpose, the verbosity could be trimmed (e.g., domain list). Earns its place but not maximally 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?

Given 6 parameters (5 aliases) and no output schema, the description adequately explains return value (names, descriptions, schemas with examples). Sufficient for a discovery tool with good 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%, so baseline is 3. The description adds minimal parameter meaning beyond schema—lists aliases and examples but doesn't explain beyond what's already in 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 'Find tools by describing the data or task,' providing a specific verb and resource. It distinguishes itself from siblings like 'query' or 'search_datasets' by positioning as a discovery layer, especially with 'Call this FIRST'.

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 you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools.' Lacks explicit when-not-to-use but contextual enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), describes return fields (cik, recent_filings, fundamentals, patents, news, LEI), and notes that patents may soft-fail due to API sunset. This goes well beyond the annotations.

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

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

The description is somewhat long but well-structured with a bulleted list of return values. Examples are front-loaded, which helps the agent quickly understand the tool's scope. A few sentences could be trimmed without losing meaning, but overall it's efficiently organized.

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

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

Despite no output schema, the description thoroughly explains return values (cik, recent_filings with URIs, fundamentals sorted by period_end, patents with caveat, news fallback, LEI). It covers input constraints, data sources, and known limitations. For a complex tool, this is highly 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%, and the schema already describes both parameters (type and value) with enums and examples. The description reinforces that type is only 'company' and value can be ticker or CIK, and reiterates that names are not supported. While it adds useful context, the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and distinguishes itself from chaining multiple single-source lookups. The verb 'profile' and resource 'US public company' are specific and unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when not to use: 'names not supported (use resolve_entity first).' This provides clear when-to-use and alternative guidance.

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

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

Annotations already provide destructiveHint=true, so description's 'Delete' adds no new behavioral info. It adds context about use cases, but not unique behavioral traits beyond annotations.

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

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

Two sentences: first states purpose, second provides usage guidance. No wasted words, front-loaded with key information.

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

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

Simple single-param tool with annotations covering destructiveness. Missing mention of idempotency (idempotentHint=true) or behavior on missing key, but completeness is high given tool simplicity.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description only says 'by key', adding no extra meaning beyond schema. Baseline 3 applies.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. It distinguishes from siblings like remember and recall by pairing them, indicating this is the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Pairs with remember and recall, guiding agent on 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: fetches page, extracts title/description/key links, emits standard markdown format. No contradiction; adds process and output details.

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

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

Two sentences, front-loaded with main action. The second sentence lists use cases effectively. Could be slightly more concise but no wasted words.

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

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

Covers input, process, output format, and use cases. No output schema needed as description explains output is a single text blob. Complete for a simple generation tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds that max_links defaults to 25 and max 50, providing additional meaning beyond schema.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It distinguishes this tool from siblings by focusing on the standard llms.txt generation, unlike scanning or research 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?

Explicit use cases are listed: getting a client's site indexed, drafting for own project, auditing competitors. Does not explicitly state when not to use, but the specificity provides clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return field details and optional include_inactive parameter. No contradictions.

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

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

Two sentences, no filler, front-loaded with the action. Every sentence adds value.

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

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

Given simple tool with 1 parameter, good annotations, and no output schema, the description covers functionality, use cases, and return fields 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 coverage is 100% for the only parameter (include_inactive). Description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Clearly states the action ('List the caller's active subscriptions') and specifies the returned fields (id, type, params, etc.). Distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicit use cases provided: review before adding more or to find an id to cancel. Does not include negative cases 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 are minimal (readOnlyHint=false etc.), but the description supplies behavioral context beyond them: rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and that the team 'reads digests daily and signal directly affects roadmap.' No contradiction with annotations.

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

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

The description is long, but it covers multiple complex aspects (types, exclusions, token flow, rate limits, quota). Every sentence is informative; however, a few sentences like 'The team reads digests daily and signal directly affects roadmap' are motivational rather than directly actionable, and the block is one dense paragraph without structural breaks. It earns a 4.

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 (four parameters, optional claim_token, multiple feedback types) and the absence of an output schema, the description provides complete coverage: purpose, when/when-not, token semantics, rate limits, and expected response behavior. An agent can use it correctly without further clarification.

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

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

Although the input schema already describes all four parameters (100% coverage), the description adds important usage semantics: it clarifies the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), explicitly instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and explains that claim_token can be used 'with no other arguments.' This goes beyond the schema's per-parameter descriptions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a clear verb+resource statement. It explicitly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes this from sibling tools like ask_pipeworx or query by framing it as reporting issues about Pipeworx itself.

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

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

The description states exactly when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This satisfies 'explicit when/when-not/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?

Beyond annotations (readOnly, idempotent), the description adds data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). Provides full transparency.

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

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

Three sentences with no fluff: first sentence states function, second lists use cases, third gives details. Very efficient and well-structured.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return values, usage context, caching, and data source. No obvious gaps.

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

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

Schema already covers the single 'window' parameter with enum and description. The description adds context on how shorter vs longer windows affect what's surfaced, which 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 returns top tools, packs, and call volume over a window, and provides three specific use cases. It distinguishes from sibling tools by focusing on aggregate trending 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?

Explicitly lists three situations where the tool is useful (discovering hot data sources, confirming popular tool, checking alignment). 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 indicate read-only, idempotent, open-world, and non-destructive hints. The description adds extensive behavioral details: walks child markets, checks order and partition sums, performs fill checks against live order book, filters partitions with placeholders, and uses semantic similarity to prevent mismatches. 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 dense but front-loaded with the core purpose and modes. While thorough, it could benefit from clearer section breaks or bullet points to improve readability. However, every sentence adds value and avoids 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 details the response structure (opportunities array, partition_check object, fill_check fields) and references related tools. For a complex tool with no output schema, it is remarkably complete, covering behavior, constraints, and edge cases.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains what event slugs look like, that full URLs work, what topic strings are used for, and how the behavior differs between parameters. It provides examples and clarifies internal logic like semantic anchor and partition filter.

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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with explicit details.

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

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

The description provides explicit guidance on when to use each parameter: no args for trending scan, event for a specific market slug, topic for cross-event scanning. It also mentions an alternative (polymarket_fill_risk for custom sizing) and conditions like when not to trade.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the three model families, caching behavior (1h at KV level), tradeable-edge knobs, response structure including diagnostics, and per-opportunity fields. It adds substantial behavioral context that aids correct invocation and interpretation.

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 clear sections (model families, opportunity fields, knobs, response top-level) and front-loads the primary use case. While lengthy, every sentence adds value. Minor verbosity in the model family details could be trimmed slightly, but overall it is appropriately detailed for the tool's complexity.

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

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

The description comprehensively covers all aspects needed for an AI agent to use the tool correctly: input knobs, output structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields, caching behavior, and filter logic. Given the lack of an output schema, the description fully compensates, leaving no critical gaps.

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

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

With 100% schema description coverage, the baseline is 3. The description adds extra meaning by explaining how parameters like min_kelly, max_spread_pp, and min_partition_leg_kelly interact with the logic (e.g., min_kelly skips small opportunities, min_partition_leg_kelly filters thin partitions). This context enhances 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 clearly states that the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and is built for 'what should I bet on today' discovery. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven, structural arbitrage, and concentrated longshot segments, making its purpose specific and actionable.

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 for daily betting discovery ('what should I bet on today'), providing clear context for when to use it. While it does not explicitly list alternatives or when not to use, the detailed explanation of segments and knobs implies usage scenarios. The omission of direct exclusions prevents a score of 5.

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

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

The description adds significant behavioral context beyond annotations: it details the output structure (tracked, expired, snapshot_dates), computation of decay and trend, sign conventions, and limitations (TTL, cache-miss behavior). Annotations only state idempotence and read-only, which are supported.

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

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

The description is relatively long but well-structured with clear sections. It is front-loaded with purpose, and each sentence adds value. Slight verbosity could be trimmed, but overall efficient.

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

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

Despite no output schema, the description fully explains the return format and fields. It covers limitations and edge cases, making it complete for an AI to understand usage and results.

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

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

Schema coverage is 100% with parameter descriptions. The description adds defaults and constraints (clamp, window families) and explains the meaning of window in context of snapshot families, enhancing the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry built from daily snapshots, answering a specific question about edge duration. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explains when to use the tool (to assess edge persistence and decay) and provides concrete examples (fresh vs. old wide edge). It does not explicitly list when not to use or alternatives, but the context is clear enough for an AI to decide.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description reinforces that it's a read-only check (no side effects) and adds behavioral details: walks the order book, returns verdicts (clean/degraded/cannot_fill), and alerts about forced directional risk. No contradiction.

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

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

The description is relatively long but well-structured: starts with purpose, then required params, then mode explanations, return fields, and usage guidance. Every sentence adds value, though it could be slightly more concise. Front-loaded effectively.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is remarkably complete. It lists all return fields for both modes, explains pitfalls (thin legs, forced directional risk), and provides practical guidance. Fully carries the burden of explaining behavior.

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%, giving baseline 3. The description goes beyond by explaining default sizes (1000), how size_usd is interpreted differently for single-market vs basket, and the auto-default logic for side in basket mode. Adds meaningful context 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 identifies the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes with specific return fields (top_of_book, vwap_fill_price, etc.). It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and book depth.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about when not to use it: theoretical overround on thin books is not capturable, and partial basket fills convert arb into unhedged directional position. Provides clear context and 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses rich behavioral details: compatibility_warning/codes can be non-empty even when matched_pairs > 0, unknown legs are never paired, skipped categories are counted, and topic mode always sets premapped_pairing_unverified. It also warns that pre-mapped ≠ tradeable, which is exactly the kind of behavioral nuance an agent needs.

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 the complexity warrants it. It is organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose before details. Some caveats are repeated, but each sentence contributes important operational information rather than 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 having no output schema, the description covers expected response components, safety fields, compatibility codes, skipped-comparison counters, temporal alignment, and the semantics of returned pairs. It also documents failure modes and the current rarity of tradeable spreads. Nothing essential for invoking or interpreting the tool 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%, which sets a baseline of 3, but the description adds meaningful semantic context: it enumerates the 10 topic shortcuts, explains that explicit tickers override the mapped side, and clarifies the difference between topic-driven auto-matching and manual pairing. This goes beyond the schema's minimal field 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 names the exact resource ('Cross-venue spread between Kalshi and Polymarket') and the clear purpose: comparing prices for the same resolving question. It immediately distinguishes this from sibling tools by emphasizing cross-venue Kalshi/Polymarket comparison and explicitly describing two operational modes. This is specific and actionable.

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 clearly explains when to use the `topic` shortcut mode versus the explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, including how overrides work. It also gives important usage cautions: pre-mapped topics do not guarantee tradeable spreads and most topics currently return warnings. It does not explicitly name alternative sibling tools, but the in-tool mode guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description is not burdened with safety disclosure. The description adds value by detailing the query language (ODSQL) and supported clauses (filter, aggregate, sort, paginate), enhancing understanding of capabilities beyond annotations.

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

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

The description is a single sentence that front-loads the core purpose and succinctly lists supported operations with parenthetical grouping. Every word is necessary and 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?

With no output schema, the description omits the return format, but for a query tool the return of records is implicit. It covers all major functional aspects (filter, aggregate, sort, paginate) and the prerequisite of specifying a dataset_id. Sufficient for most use cases given good 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?

All 8 parameters are fully described in the input schema (100% coverage). The description groups parameters into conceptual categories (filter, aggregate, sort, paginate) but does not add new semantic details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Query', the resource 'SNCF Open Data dataset', and the specific ODSQL operations (filter, aggregate, sort, paginate). This distinguishes it from sibling tools like 'search_datasets' which find datasets, not query records.

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

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

The description implies usage for querying data with ODSQL, but does not explicitly state when to use this tool versus alternatives like 'search_datasets' or 'search_within'. No exclusions or comparative guidance are provided.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds scoping detail ('Scoped to your identifier') and lifecycle pairing, which 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?

Three sentences, front-loaded with the main action. Every sentence adds value without redundancy.

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

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

For a simple read-only retrieval tool with one optional parameter and no output schema, the description covers use case, scoping, and lifecycle pairing comprehensively.

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 single optional key parameter. Description reinforces the schema's description (e.g., 'omit the key argument'). Baseline 3 is appropriate; no additional parameter semantics beyond schema.

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

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

Clearly specifies verb ('Retrieve a value previously saved via remember, or list all saved keys') and resource (saved values/keys). Distinguishes from siblings like remember 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?

States when to use: 'to look up context the agent stored earlier'. Mentions pairing with remember/forget. Lacks explicit when-not-to-use or alternative tools, 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?

The description discloses that setting mark_read:true flags returned events as read, affecting subsequent calls—a state-modifying behavior. However, the annotations declare readOnlyHint=true, which implies no writes. This contradiction between description and annotation misleads the agent about the tool's side effects, leading to a low score.

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

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

The description is four sentences, front-loading the core purpose and then efficiently covering key features (filters, mark_read, polling). Every sentence adds value without redundancy or unnecessary detail.

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

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

Despite no output schema, the description explains what fields each alert carries (source, citation_uri, raw payload). It also mentions polling suitability and an alternative endpoint. For a tool with 5 optional parameters, this is sufficiently complete, though it could briefly note the structure of the payload.

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

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

Schema coverage is 100%, providing baseline parameter info. The description adds meaningful context beyond the schema: it gives an example for type ('sec_8k') and explains the effect of mark_read on future calls ('so the next call only shows newer ones'). This extra guidance moderately enhances parameter understanding.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions, which list subscriptions themselves, not events. The verb 'pull' and resource 'fired events' are specific and unambiguous.

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

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

The description implies when to use this tool (to check recent alerts) and mentions an alternative GET endpoint for scripts/dashboards, but does not explicitly state when not to use it or provide exclusions compared to other tools. The context is clear enough for an agent to infer typical usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the parallel fan-out to multiple sources, fallback behavior (GDELT→GNews on rate limit/5xx), USPTO soft-fail, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single, slightly dense paragraph but front-loaded with intuitive example queries. Every sentence adds useful information. Could be slightly improved with bullet points or separation, but is efficient overall.

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 adequately describes the return structure (changes grouped by source, counts, citation URIs). It covers sources, fallbacks, soft-failures, and the alternative tool. For a tool with good annotations and moderate complexity, this is sufficiently complete.

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

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

Schema coverage is 100% but the description enriches meanings: 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y') with example values, and 'value' can be ticker or zero-padded CIK. This goes beyond the schema's basic type/format descriptions.

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

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

The description starts with concrete example queries and states the tool's purpose as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with sibling tool entity_profile, making it easy to distinguish.

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 an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains when the GDELT→GNews fallback occurs. However, it does not list specific scenarios to avoid using this tool.

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

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

Disclosures beyond annotations: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' No contradictions with annotations (idempotentHint true, destructiveHint false).

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 concise sentences: core purpose, usage guidance, storage mechanism, retrieval pairing. No unnecessary 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?

Completely covers purpose, usage, persistence behavior, and integration with sibling tools. No output schema needed for this simple write operation.

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

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

Schema has 100% coverage with descriptions. Description adds example key patterns (subject_property, target_ticker) and specifies value as 'any text', providing extra context.

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

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

The description uses specific verbs ('Save data the agent will need to reuse later') and resources ('key-value pair'), clearly distinguishing from sibling tools like recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), provides context (authentication persistence), and pairs with recall/forget for retrieval/deletion.

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?

Although annotations already declare this operation safe and read-only, the description adds substantial behavioral detail: internal cascade of lookup endpoints, graceful degradation if GLEIF/OpenFIGI is unavailable, ambiguous matches returning figi_candidates, explicit unresolved identifiers, and ISIN-to-LEI mapping. No contradiction with annotations exists.

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

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

The description is dense and front-loaded with user intents, usage rule, and supported types; nearly every sentence carries operational guidance. It is quite long with sprawling parentheticals, which keeps it from being truly concise, but it does not waste 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?

With no output schema, the description carries the full burden of explaining return behavior: it specifies returned identifiers per type, source labels, figi_candidates for ambiguous bonds, an explicit unresolved field, and drug citation format. It also covers non-US entities, ambiguity, and enrichment degradation, making it safe to call across scenarios.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains exactly what formats `value` accepts per entity type, warns that bond lookups require the issuer name exactly as printed, and cautions that trailing security-class words match nothing. This materially improves correct invocation.

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

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

The description opens with concrete user phrasings and sharply states the tool's job: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It enumerates supported types and the identifiers returned for each, which clearly distinguishes it from sibling tools like entity_profile or validate_claim.

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

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

It explicitly instructs agents to 'Use FIRST whenever you have a name but need an ID,' providing a clear selection rule. It does not explicitly contrast itself with sibling tools by name or state when not to use it, but the rule is sufficiently directional.

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 and idempotent. The description adds significant behavioral context: it internally calls ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. 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?

Three concise sentences, front-loaded with the primary action. Every sentence contributes meaningful information without redundancy.

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

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

Given full schema coverage and no output schema, the description sufficiently covers return format (ranked list with score, confidence, signal density), internal mechanism, and use case. No gaps identified.

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

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

Schema has 100% description coverage, so parameter basics are clear. The description adds value by explaining the 'entities' array: the first entity is treated as the subject for narrative, and the rest as competitors, which aids correct invocation.

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

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

Description clearly states the verb (compare, probe, rank), resource (AI visibility across entities), and distinguishes from siblings like ai_visibility_check by emphasizing side-by-side comparison. The example use case reinforces clarity.

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

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

Provides explicit use case for competitive AI-marketing audits with a concrete question. However, it lacks guidance on when not to use this tool versus alternatives like ai_visibility_check or compare_entities.

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 safe, idempotent, read-only. Description adds composite nature, fan-out behavior, partial failure degradation with sources_failed, and timing caveat (5-30s for new version). No contradictions.

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

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

Description is comprehensive and well-structured, front-loaded with purpose. Every sentence adds value, though slightly long; could be marginally shorter without loss of meaning.

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

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

For a composite tool with multiple data sources, partial failure modes, and no output schema, the description covers all necessary context: return fields, ecosystem scope, performance caveats, and fallback guidance for other ecosystems.

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 for both parameters. Description repeats schema info (scoped packages, default version) without adding new semantics beyond what schema provides. 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 it's a composite check for 'should I add this npm package to my project' using deps.dev and bundlephobia. Unambiguous verb and resource, distinct from all sibling tools.

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

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

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

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations, such as the specific data scope (SNCF Open Data) and the exact return fields (dataset_ids, titles, themes, record counts), which helps the agent understand what to expect. No contradictions found.

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

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

The description is two sentences, front-loaded with the primary action, and includes useful examples and return information without wasted words. Every sentence earns its place, making it highly efficient and scannable.

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 is simple (3 optional params, no output schema) and the description adequately explains the return values and how the results should be used downstream. It covers the essential context for an agent to decide when and how to invoke it, without needing further elaboration.

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

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

Schema description coverage is 100%, with all three parameters (limit, query, offset) already described in the input schema. The description does not add significantly to parameter semantics—it only repeats the keyword concept. Per the baseline rule for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's function: searching SNCF Open Data datasets by keyword. It specifies the resource (SNCF open data), the action (search), and the scope (datasets by keyword), while also listing example content types (train schedules, stations, etc.) and the return payload, which distinguishes it from generic search 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 conveys when to use the tool: when you need to find datasets on SNCF Open Data. It also provides downstream guidance by mentioning that returned dataset_ids can be passed to query/dataset_info, implicitly indicating the typical workflow. However, it does not explicitly state when not to use it or compare to alternatives like search_within.

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 safe read operations. The description adds concrete behavior: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and output includes character offsets and similarity scores.

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

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

Four sentences with no fluff. Core purpose front-loaded, followed by use case and technical details. Every sentence adds value.

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

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

Given the tool's purpose, parameters, and annotations, the description covers input constraints, algorithmic details, output structure, and truncation behavior. No output schema exists, but description adequately informs the agent.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. The description adds example queries and explains limit default, but doesn't provide significant new 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 states it performs semantic search inside a retrieved document, with specific examples (SEC 10-K, article) and distinguishes it from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says when to use: when record is too large for prompt. Also mentions pairing with ask_pipeworx_grounded for grounding over passages, and notes it saves context.

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

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

Annotations indicate readOnlyHint=false (write), idempotentHint=true, destructiveHint=false. The description adds operational details: SMS cap (10/day), webhook auto-disable after 10 failures, phone verification requirement, and one-time webhook secret. However, it does not clarify idempotency behavior (e.g., whether re-subscribing with same params creates duplicate). No annotation 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 comprehensive but somewhat lengthy. It is well-structured with clear sections: purpose, prerequisite, types, delivery channels. Every sentence adds value, but could be slightly more concise without losing detail.

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 mentions the return of a subscription ID and, for webhook, a one-time secret. It covers most behavioral aspects (prerequisites, type-specific params, delivery options, limits). Missing details on error responses or duplicate subscription handling, but adequate 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 coverage is 100% with descriptions for all parameters. The description adds rich, type-specific examples (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and detailed delivery channel behavior (email pattern, SMS E.164, webhook signing). This significantly extends the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It uniquely identifies the resource (subscription) and action (create), and differentiates from siblings like unsubscribe and list_subscriptions through types and delivery details.

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 requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It provides guidance on when to use each subscription type with examples, but does not explicitly exclude scenarios where alternatives like recent_alerts or ask_pipeworx would be better suited.

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

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

Annotations declare readOnlyHint and idempotentHint. Description adds behavioral detail: returns example questions with exact tool+argument shape, drawn from live catalog. No contradictions. 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?

Description is well-structured with front-loaded trigger phrases and parentheses. Dense but every sentence adds value. Slightly long but appropriate 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?

No output schema, but description explains return format clearly. Covers all necessary context: when to use, what it returns, how to call, and examples. Complete for the tool's purpose.

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

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

Schema coverage is 100% with description for topic parameter. Description adds context: 'Omit for a cross-category spread', lists example topics, and explains behavior with and without argument. Highly enhances schema.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions with exact tool calls. It distinguishes from siblings by stating 'Use this FIRST' and listing what it covers, differentiating it from specialized tools like ask_pipeworx or entity_profile.

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

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

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'or to learn how to call the meta-tools'. It does not explicitly state when not to use, but the 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?

Discloses key behavior beyond annotations: row is deactivated (not deleted) and historical events remain accessible. Annotations already indicate non-destructive and non-read-only, so description adds value.

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

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

Two succinct sentences, front-loaded with action, no filler words. Earns its place efficiently.

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 1 param and no output schema, the description fully covers usage constraints and post-invocation state. No missing context.

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

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

Schema covers id with description 'Subscription id (uuid) returned by subscribe.' Description adds no param-specific info beyond 'by id', which is already implied. Schema coverage 100% sets baseline at 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?

Clear verb-resource pair: 'Cancel a subscription by id.' Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement ('only your own subscriptions') and the soft-delete behavior, helping the agent understand when and how to use it.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds significant behavioral context: internal pipeline (SEC EDGAR + XBRL fast path, grounded fallback), verdict types, and the crucial clarification that could_not_verify means the check did not happen and must not be treated as evidence. This is valuable beyond the annotations.

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

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

The description is long but front-loaded with purpose and query phrasings. Each sentence carries meaningful operational information (pipeline steps, verdict semantics, caller warning, efficiency comparison). It could arguably be tightened, but the length is justified by the tool's complexity and there is no filler. Structure is logical and clear.

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

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

With no output schema, the description fully specifies the return structure (verdicts, actual value with citation, reasoning) and elaborates on edge cases (could_not_verify with verification_error, unsupported). Combined with the rich parameter schema and annotations (read-only, idempotent), the description leaves no major operational gap 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%: both claim and tolerance_pct have detailed descriptions with examples and defaults. The tool description does not add parameter-specific meaning beyond the schema; it mentions 'exact percent-delta math' in passing but that is more behavioral than parameter guidance. Baseline 3 is appropriate due to high 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: natural-language claim verification against authoritative sources. It lists specific query phrasings ('Is it true that...', 'fact check', 'verify the claim that...') and explicitly says to use it when checking if something a user said is factually correct. It also distinguishes itself from siblings by noting it replaces 4–6 sequential calls and handles two distinct pathways (structured SEC EDGAR vs grounded fallback), making it uniquely suited for fact-checking.

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 context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the two scenarios (company-financial claims via SEC EDGAR, any other claim via grounded pipeline). However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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