Data Issy

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral context like cost implications (free Workers AI vs. BYO key for Anthropic) and the return structure (per-model score+confidence+signals+raw_response). This provides useful transparency 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 core purpose, then detailed parameters and use cases. Every sentence adds value with no redundancy, making it efficient for an agent to parse.

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

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

Despite lacking an output schema, the description fully explains return format (per-model + combined view). All parameters are described with purpose, and the tool's complexity (multi-model, optional key) is well captured. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning: it specifies the default model, explains when _apiKey is needed, and describes how the context parameter aids disambiguation. This enriches the schema information for an agent.

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

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

The description clearly states the tool probes LLMs for brand/product/topic awareness and scores visibility, listing specific use cases like AI-marketing audits and competitive monitoring. This distinguishes it from sibling tools like ask_pipeworx or deep_research which serve different purposes.

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

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

The description tells when to use the tool (AI-marketing audits, pre-launch checks, monitoring) and mentions default vs. paid model options. However, it does not explicitly state when not to use it or compare to alternatives, leaving some ambiguity for the agent.

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 establish read-only/idempotent/open-world safety. Description adds operational context: it routes to tools, fills arguments, returns structured answers with stable citation URIs, and works on every tier. It also reveals output shape ('single answer with verbatim evidence') and that it can route to live-news packs, going well 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 long but front-loaded ('PREFER OVER WEB SEARCH') and packed with actionable routing guidance, domain list, examples, and alternatives. Minor redundancy ('START HERE' vs 'Default entry point') keeps it from a 5, but no sentence is wasted.

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 routing tool with no output schema, the description covers scope, input, output format (structured answer + citations), tier availability, and alternatives. It doesn't mention ask_pipeworx_beta or describe failure/limitations, but that is not critical given the breadth of information provided.

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

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

Input schema already documents question and aliases with examples at 100% coverage. Description reinforces that the parameter is a natural-language factual question and offers trigger phrases, but does not add syntax, constraints, or meaning substantially 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?

States a precise function: routes a natural-language question to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. Explicitly frames itself as the default alternative to web search ('PREFER OVER WEB SEARCH', 'START HERE for most questions'). Distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and domain examples (SEC filings, FDA data, weather, clinical trials). Names alternatives with conditions: ask_pipeworx_grounded for focused single answers, deep_research for multi-part/broad questions, and notes ask_pipeworx handles breaking news live. This is strong when/when-not 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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which are comprehensive for safety and side-effect clarity. The description adds that this is the experimental edge, that candidate routing improvements are live only when under test, that none is currently active, and that it returns the same response shape as the stable router. It does not contradict annotations and gives useful context beyond the structured hints.

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

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

The description is a compact paragraph with essential context, front-loading the beta identity and equivalence to ask_pipeworx, then explaining the experimental routing behavior and current status. It is somewhat longer than strictly necessary but each sentence adds distinct information: identity, scope, behavior, usage instruction, and fallback guarantee. No redundancy.

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

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

Given no output schema, the description should explain what the agent can expect. It states the same response shape as ask_pipeworx, which is sufficient because the sibling tool presumably defines the shape. It also clarifies that it is fully functional and not a stub, preempting the main risk in beta tools: unreliability. The only minor gap is not explaining what routing improvements are or how results are compared, but that is not necessary for invoking the tool, and the explicit equivalence to ask_pipeworx covers usage expectations.

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 description of the question parameter and its aliases fully documented. The tool description adds no additional semantics beyond the schema because it explicitly says same arguments as ask_pipeworx, but the schema already covers all six parameters comprehensively. A baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx—a universal router with the same tool set, arguments, and response shape as the stable sibling—while specifying the current status (no active candidate, currently identical to ask_pipeworx). It distinguishes itself from ask_pipeworx by positioning as the experimental edge for comparing routing improvements.

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

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

It explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the purpose of results comparison against the stable router and explicitly warns it falls back to nothing, meaning it is a full working router rather than a stub. This provides clear context and disambiguates from sibling ask_pipeworx.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits. The description adds substantial behavioral detail beyond that: the tool routes through 5,798 tools, fills arguments, extracts answers only from tool results, returns a structured success payload, and explicitly refuses with enumerated reasons when data cannot answer. There is no contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, behavior, output shape, refusal semantics, use cases, and cost tradeoff. It is front-loaded with the most important differentiator, 'Hallucination-resistant answer mode,' and the return/refusal contract is compactly 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?

Given the tool's complexity and the absence of an output schema, the description fully compensates by specifying the success payload, the refusal payload, the exact refusal reasons, and the extra-LLM-call cost. It also names the sibling to prefer for casual use, making the decision context 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%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that the question parameter is automatically routed, that the tool picks the right underlying tool, and that arguments are filled on the agent's behalf. This tells the caller that only a natural-language question is needed and no structured arguments should be supplied.

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

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

The description opens with a specific verb-resource pair: 'Hallucination-resistant answer mode' and immediately distinguishes itself from ask_pipeworx by explaining the grounded extraction behavior. It clearly states this tool is for high-stakes reads and is not the same as the casual ask_pipeworx mode.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also gives an explicit when-not-to-use instruction: 'prefer ask_pipeworx for casual lookups' with the cost tradeoff clearly stated.

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 extensive behavioral detail beyond annotations: market resolution, classification, fan-out, evidence packet, safety mechanisms (low-confidence short-circuits, closed markets, wide spreads), resolver contract, parent event extraction, and cancellation rules. 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 lengthy but well-structured with clear sections (e.g., 'RESPONSE SHAPES', 'RESOLVER CONTRACT', 'SAFETY'). It front-loads purpose and usage. While verbose, every sentence adds necessary detail for a complex tool.

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

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

Given the tool complexity (3 parameters, no output schema), the description covers all aspects: purpose, usage, fan-out behavior, response shapes, resolver contract with match confidence, parent events, news fields, safety, cancellation rules. 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 description coverage is 100% with detailed parameter descriptions in the input schema. The main description explains market accepts slug, URL, or question text but does not add new meaning for depth or include_raw beyond what schema already provides. The fan-out examples implicitly show depth usage. Overall adequate but not exceeding baseline 3.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It uses specific verbs ('research') and resources ('Polymarket bet', 'Pipeworx data'). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on a single bet research rather than edges or arbitrage.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-out based on categories. However, it lacks explicit guidance on when not to use or direct alternatives.

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

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

Annotations already indicate safe, read-only behavior. The description adds valuable context: data sources (EDGAR/XBRL, FAERS), handling of fiscal years, and result sorting.

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

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

Concise yet comprehensive: starts with trigger phrases, then usage guidance, then per-type details, then output structure. No redundant sentences.

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

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

Given the simplicity of inputs and rich annotations, the description adequately covers data retrieved, sorting, and citation output. Lacks explicit output format but sufficient.

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

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

Schema covers both parameters fully. The description adds richer context for each enum and explains input formats for values, enhancing 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 identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides trigger phrases and distinguishes from sequential lookups.

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

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

The description explicitly advises preferring this tool over sequential lookups for comparisons. It covers when to use but lacks explicit exclusion scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by specifying it is a prerequisite for query and details the metadata returned, complementing annotations without contradiction.

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

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

Single sentence with no wasted words. Front-loaded with verb and main purpose, followed by specifics and usage hint. Efficient and clear.

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

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

Given simple tool (1 param, no output schema), description fully covers what is returned (fields/schema, themes, record count) and usage context. No missing information.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context that dataset_id comes from search_datasets, which reinforces the parameter's purpose beyond the schema description.

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

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

Description clearly states 'Get metadata for one Issy-les-Moulineaux Open Data dataset' with specifics (fields/schema, themes, record count). It distinguishes from siblings like search_datasets by indicating it's for a single dataset and should be called before query.

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

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

Explicitly says 'call before query to learn the column names', providing clear context for when to use. While it doesn't name alternatives explicitly, the sibling set includes query, search_within, etc., making the guidance effective.

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

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

The description discloses the auth requirement and paid tier, expected latency (15-60s, up to ~90s for thorough), parallel routing to 5,798 tools, explicit gaps[] with 'never invented', contradictions[] for standard/thorough, semantic excerpting, and resolvable citation_uri. Annotations (readOnly, openWorld, idempotent) are consistent — no contradiction — and the description adds substantial behavioral context 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 long but dense — nearly every sentence adds needed context (auth, scope, decomposition, output packet, depth differences, latency). Minor deductions because the purpose statement is deferred behind the account-requirement and fallback-tool sentences, and some depth behavior overlaps with the schema's enum descriptions.

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

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

Without an output schema, the description thoroughly compensates by defining the findings packet: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri resolvability. Combined with annotations and schema, an agent has enough to invoke the tool and interpret its result correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics beyond the schema: depth:'thorough' requires a paid plan, latency implications for each depth, and the note that multi-step questions resolve in one call. It does not fully re-document parameters but enriches the practical meaning of depth.

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

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

The description names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call, with parallel decomposition into facets. It also distinguishes from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx instead.'

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It names an alternative and the switching condition: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.'

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds valuable context: results include full schemas and are ready to call directly, no second lookup needed.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value without fluff.

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

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

For a tool with 6 parameters and no output schema, the description adequately explains the return format (names, descriptions, schemas) and usage context, though it could mention error handling or limits.

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, but the description adds meaning by listing aliases (task, q, description, search) and explaining that multiple parameters are accepted, enhancing schema info.

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

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

The description clearly states the tool finds tools by describing data or task, lists specific domains, and distinguishes itself from sibling tools like 'query' and 'search_datasets' as a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use guidance and implying it should precede other tool calls.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavior beyond them: parallel fan-out across seven sources, GDELT→GNews fallback, USPPTO API sunset soft-fail, and most valuably, 'an empty section is a real "no data", not a bug' with sources_used/sources_failed accountability. It also discloses the resolved:false + notes path for private companies so an agent won' t misclassify a valid outcome as an error.

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

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

Well front-loaded with example queries and the core value proposition, and length is proportionate to the tool's multi-source complexity. Nearly every sentence earns its place, though a few points (ticker/CIK/name input format, `type` interchageability) duplicate what the input schema already documents.

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 return-value burden and meets it fully: it enumerates cik/company_name, recent_filings with pipeworx URIs, fundamentals fields, per-source sections, and sources_used/sources_failed. Input formats, name-resolution fallbacks, and expected-empty conditions (e.g., small-molecule drug companies showing no fda_products) are all covered, leaving no significant ambiguity for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties `value` to resolution consequences (resolved_from/resolved_to, SEC EDGAR name matching, private-company resolved:false) and clarifies that `type`'s enum values are interchangeable. Some repetition of schema content prevents a 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 states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call,' anchored by example queries like 'Tell me about X' and 'brief me on Tesla.' It distinguishes itself from alternatives by framing itself as the holistic view to prefer over chaining single-pack SEC/XBRL/news lookups.

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

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

Includes an explicit when-to-use rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Scope boundaries are clear ('US public company', 'person/place coming soon', private-company fallback), but it never names sibling tools like resolve_entity or compare_entities for non-profile intents, so exclusion guidance is partial.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which reinforces the behavioral disclosure. No contradictions.

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

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

Two concise sentences that cover purpose, usage, and pairing. No fluff.

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

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

For a simple single-parameter delete tool without an output schema, the description is complete: it explains what the tool does, when to use it, and how it relates to siblings.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description does not add extra information about the key format or constraints, so baseline 3 applies.

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

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

The description clearly states the verb ('delete') and the resource ('previously stored memory by key'). It distinguishes from siblings by contrasting with 'remember' and 'recall'.

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

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

Explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', providing clear guidance on when to use this tool vs. 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?

Discloses external fetch behavior and extraction process beyond annotations (readOnlyHint=true, destructiveHint=false). Could mention rate limits or caching but 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?

Three sentences, front-loaded with main purpose, then details, then use cases. No fluff.

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

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

Covers purpose, behavior, and output format. Lacks error handling or prerequisite info, but sufficient for a simple fetch-and-generate 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?

Both parameters are fully described in schema (100% coverage). Description reiterates URL and max_links defaults, adding no new information beyond schema.

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

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

Description clearly specifies verb 'generate' and resource 'llms.txt file' for any URL, and distinguishes from sibling tools by focusing on AI crawler indexing, which no sibling does.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing), providing clear context for when to use.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. Description adds detail on return fields and default scope (active only), going beyond annotations, though not addressing openWorldHint possible side effects.

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

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

Two concise sentences with no waste; first sentence states purpose, second provides usage guidance.

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 tool with one parameter and rich annotations, the description sufficiently covers purpose, return data, and usage context.

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

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

Schema coverage is 100% with description for the sole parameter. Description adds no further meaning beyond what schema provides, so baseline 3.

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

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

Clearly states it lists the caller's active subscriptions, specifies returned fields (id, type, etc.), and is distinguishable from subscribe/unsubscribe siblings as the read 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 advises use before subscribing more or to get IDs for cancellation. Implicitly contrasts with subscribe/unsubscribe but doesn't state explicit alternatives or when not to use.

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

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

Annotations are all false, so the description carries the full burden. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism, the fact that it's free and doesn't count against quota, and that the team reads digests daily. These are substantial behavioral traits beyond what annotations provide.

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

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

Although longer than average, every sentence earns its place: purpose, usage conditions, exclusions, claim_token flow, impact, and rate limit. It is front-loaded with the core purpose and contains no redundancy or filler.

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

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

Given no output schema, the description explains the return value ('returns a claim_token'), the follow-up mechanism, and constraints. The 4 parameters, nested object, and enum are fully addressed through the combination of description and schema, with no significant 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 coverage is 100%, but the description adds critical usage semantics: the claim_token is to be passed 'with no other arguments' and can be used to read the reply. It also instructs to describe issues in terms of Pipeworx tools/packs and not paste the end-user's prompt, enriching the message and context parameters.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature, data_gap, praise) and distinguishes this tool from siblings like ask_pipeworx and discover_tools by framing it as a direct feedback channel.

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

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

It provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug)...' and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection.' It even directs users to file with the other server if the tool came from a different MCP server, giving clear 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 cover read-only, open-world, idempotent, non-destructive. Description adds valuable context: derived from analytics engine, no PII, caching behavior (5min-1h). 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?

Well-structured with bullet points and clear sections. Slightly lengthy but every sentence adds value; front-loaded with main output.

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

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

Despite no output schema, description explains the return structure (top tools, packs, volume) and caching behavior. Complete for a simple list tool with one optional parameter.

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 high coverage and describes the window parameter. Description reinforces the meaning of different windows ('surfaces what's hot right now' vs 'steady-state demand'), adding practical 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?

Explicitly states it returns top tools, packs, and call volumes over specified windows. Provides three distinct use cases, differentiating it from sibling tools like discover_tools 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?

Lists three specific scenarios (discovering hot data sources, confirming canonical tools, aligning use cases). Does not explicitly mention when not to use, but context signals imply alternatives exist.

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

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

Annotations already indicate read-only, open world, idempotent. Description adds internal logic details like monotonicity checks, partition sum, semantic anchor, partition filter, and fill check, providing full behavioral 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?

The description is long but well-structured: general purpose, parameter modes, internal details. Every sentence adds value, though slightly verbose for a concise ideal.

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 modes, internal checks), the description covers all necessary aspects: input modes, internal logic, edge cases (placeholder filter, similarity), response structure, and when to use sibling tools. No output schema needed as response is explained.

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

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

Schema coverage is 100%, but description adds significant meaning: explains the differences between event and topic modes with examples, internal processing, and response details, far exceeding baseline.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges by focusing on arbitrage, not just edges or spreads.

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

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

Explicit guidance on when to use each parameter: no args for trending_scan, event for specific market, topic for cross-event scanning. Also warns when not to trade based on fill check and references polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: caching at KV level keyed on all knobs with 1h TTL, how segments work, diagnostics for empty results, and the Fed bets exclusion. 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 very detailed and front-loads the purpose, but it is quite long (multiple paragraphs) with extensive mathematical detail on model families and implementation specifics. While structured with bullet points, it could be more concise. The verbosity may reduce readability for some agents.

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 9 parameters, no output schema, and the complexity of the tool, the description is highly complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the meaning of edge fields, and how filters work. All essential information for an agent to use the tool effectively is present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema's descriptions, e.g., explaining slippage_pp with actual market context (zero fees but bid/ask depth eats 20-50bp) and the purpose of min_partition_leg_kelly for partition arbs. Most parameters get extra detail.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarkets' to find opportunities where Pipeworx data disagrees with market prices. It is built for 'what should I bet on today' discovery. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker, which likely have different scopes.

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

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

The description explains that the tool is for initial discovery without paging through hundreds of markets. It details the three segments (model-driven, structural arbitrage, concentrated longshot) and the tradeable-edge knobs (min_liquidity, max_spread_pp). It does not explicitly state when not to use it versus alternatives, but the context implies it is for opportunity scanning, not for detailed tracking (which sibling tools may handle).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant context: history bound by 60-day TTL, snapshot gaps explained, decay computed from daily closes (not intraday), and detailed response structure (tracked[], expired[], snapshot_dates[] with meanings for each field). No contradictions.

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

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

The description is relatively long but well-structured: purpose first, then detailed response and limits. Every sentence adds value. Could be slightly more concise but remains clear and informative.

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

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

Given the annotations (readOnly, idempotent, etc.) and no output schema, the description fully covers what the tool returns (tracked, expired, snapshot_dates), how to interpret values (signed edge, trend flags, decay), and operational limits (TTL, snapshot gaps). 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 coverage is 100%, so baseline is 3. The description adds extra context: explains days as 'lookback' with default/max, window as 'snapshot family' with defaults, and clarifies how parameters affect results (e.g., gaps in snapshot_dates). Also describes the response format, which is not in the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical depth rather than current edges.

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

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

The description implies when to use: for evaluating edge persistence vs. freshness, contrasting a fresh wide edge with a 3-week-old one. It gives context on when this tool adds value but does not explicitly exclude alternatives or mention sibling tools by name.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict (clean|degraded|cannot_fill)'. Also explains basket mode returns and forced directional risk. No contradiction with annotations. The description goes beyond the safety profile to explain the internal logic and risk implications.

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 but well-structured: starts with overall purpose, then separated sections for single-market and basket modes using ALL-CAPS headers. Each section lists inputs and outputs. Front-loaded with key purpose. Some redundancy (e.g., size_usd description repeated in schema and text) but overall efficient for the complexity. No wasted sentences.

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

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

Given no output schema, the description thoroughly explains return values for both modes: lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. Also explains the risk of partial fills. Covers all necessary context for safe and effective use.

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

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

Schema coverage is 100% (all 4 parameters described in schema). Description adds meaning: explains that size_usd is 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional — shares per leg' for basket. Clarifies that side default for basket is 'auto — sell if partition sum > 1, buy if < 1'. Also notes clamping range for size_usd (10–1,000,000). This significantly enriches the schema descriptions.

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

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

Description clearly states the tool does a 'realizable-vs-theoretical edge check against live CLOB order-book depth' in two modes (single-market and basket). It distinguishes from siblings by explicitly saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. The verb 'check' and resource 'fill risk' are specific.

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

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

Explicitly states when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Provides requirements: 'REQUIRES one of market (single-market mode) or event (basket/partition mode)'. Also explains when not to use or why it's needed: 'theoretical overround on thin books is not capturable' and warns about partial basket fills converting arb to unhedged directional position, which is the dominant loss mode.

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 is unusually transparent about matching behavior: it discloses that pairs are keyword-matched rather than verified by a shared resolution source, that unclassified legs are never paired, that temporal-alignment unknowns are not confirmations, and that spreads are gross of Kalshi fees. It adds significant interpretive context beyond the readOnly/idempotent annotations and warns the caller exactly what the tool can and cannot guarantee.

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 labels for modes, response, safety fields, and codes, and it front-loads the core purpose. However, it is very long and somewhat repetitive — for example, the temporal_alignment_unknown caveat is stated multiple times — so not every sentence fully earns its place.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers response shape, safety fields, compatibility codes, per-entry flags, fees, skipped comparison counters, and the real-world caveat that most macro shortcuts are not tradeable. An agent has enough context to invoke the tool correctly and interpret ambiguous results.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful behavioral semantics by explaining that both modes run the identical token-overlap matcher, that explicit ticker/slug overrides the topic-mapped side, and how the two modes differ. This goes beyond what the schema alone conveys, though the schema already provides good examples and values.

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

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

The description opens with a precise statement of what the tool does: it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from related tools by emphasizing the two-venue comparison and by naming its two operating modes explicitly.

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

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

The description gives clear guidance on the two modes — topic shortcuts for pre-mapped events and explicit ticker/slug for custom pairings — and cautions that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly name alternative sibling tools (e.g., polymarket_arbitrage) or state when to prefer them, but it does explain the relevant within-tool usage decisions well.

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 destructiveHint=false. Description adds context: only works with Issy-les-Moulineaux Open Data datasets, which is useful 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?

Single sentence, front-loaded with verb and resource, no wasted words. 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?

Covers main behavior and source constraint. Lacks mention of return format or behavior of 'query' vs 'where' parameters, but adequate for most use 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% (baseline 3). Description groups parameters into ODSQL clauses (filter, aggregate, sort, paginate), adding clarity beyond individual 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?

Description clearly states it queries records from Issy-les-Moulineaux Open Data using ODSQL, listing capabilities (filter, aggregate, sort, paginate). This distinguishes it from siblings like search_datasets and dataset_info.

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?

Implied usage for querying dataset records, but no explicit guidance on when to use vs alternatives like search_within, and no exclusions or prerequisites mentioned.

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 idempotentHint=true. Description adds scoping context (anonymous IP, BYO key hash, account ID) and pairing usage, enhancing understanding beyond annotations.

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

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

Three informative sentences, no redundancy, front-loaded with purpose. 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 simple tool (one optional param, annotations present, no output schema), the description adequately covers retrieval, listing, scoping, and pairing. Complete for an agent's needs.

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 already describes the key parameter's behavior (omit to list all keys). Description repeats that information without adding new semantic detail beyond usage 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?

Description uses specific verbs 'retrieve' and 'list', names the resource as saved values/keys, and distinguishes from siblings '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?

Explicitly tells when to use (look up stored context) and implies not to re-derive. Mentions pairing with remember and forget, but no explicit when-not-to-use or sibling comparisons.

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 reveals that setting mark_read:true flags events as read, which is a write operation. This contradicts the annotation readOnlyHint=true, which indicates the tool is read-only. The description is transparent about the mutation, but the contradiction with the annotation forces a score of 1 per the scoring rules.

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 concise sentences with no fluff. The first sentence establishes purpose, the second covers return fields, the third explains filtering and mark_read, and the fourth provides an alternative access method. Every sentence earns its place.

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

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

Despite having no output schema, the description explains the return fields (source, citation_uri, payload), covers all parameters, gives an alternative endpoint, and mentions polling suitability. It provides sufficient context for an AI agent to use the tool correctly.

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

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

The schema coverage is 100%, and the description adds meaningful context beyond the schema descriptions. It explains the effect of parameters like 'Filter by type (e.g. sec_8k) and/or since (ISO timestamp)' and how mark_read affects subsequent calls. This adds value but the schema already describes each parameter.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed'. It specifies the verb (Pull, Returns), the resource (fired events from subscription feed), and distinguishes from siblings by mentioning an alternative access method via GET endpoint.

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 retrieve recent alerts with optional filtering by type and timestamp, and to manage read state. It mentions polling works fine and provides an alternative for scripts/dashboards. While it doesn't explicitly say when not to use it, the context is clear enough for an AI agent.

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?

Despite annotations already indicating safe read operations, the description adds valuable context: parallel fan-out to multiple sources, fallback logic, rate-limit handling, and patent source status.

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

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

Long but every sentence is informative, front-loaded with examples, and efficiently structured with no wasted words.

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

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

Completely covers the tool's complexity: multiple sources, fallback, date parsing, return structure (grouped changes, count, URIs). No output schema but description provides necessary details.

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 meaningful usage details: type='company' only, since accepts ISO or relative (recommends '30d'), and value accepts ticker or CIK.

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 provides a change feed for a company (SEC filings, news, patents) and explicitly distinguishes from the sibling 'entity_profile' tool.

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

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

Provides explicit query examples ('What's new with X', 'latest on Y'), explains fallback behavior, and tells when to use 'entity_profile' instead.

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, describes scoping by identifier, persistence differences for authenticated vs anonymous, and 24-hour retention. No contradictions with annotations (idempotentHint, destructiveHint).

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, then usage, then behavioral details. No superfluous content. 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 simplicity (2 params, no output schema), description covers purpose, usage, behavioral traits, and pairing with siblings. Fully adequate for correct invocation.

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

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

Schema coverage is 100%, so baseline 3. Description adds context like 'scoped by your identifier' and examples of key names, which enriches 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?

Clearly states verb 'save' and resource 'data', with specific examples (key-value pair, cross-session reuse). Distinguishes from sibling tools recall and forget.

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

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

Explicitly describes when to use: discover something worth carrying forward. Lists concrete use cases (resolved ticker, target address, user preference). Pairs with recall and forget as 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing fallback behavior (LEI/FIGI enrichment degrades gracefully, EDGAR identifiers still return), source labeling, explicit treatment of unresolvable identifiers under `unresolved`, and internal cascading through multiple endpoints. It also explains how ISINs are mapped to legal entities. This gives an agent an accurate mental model of what happens under success and partial-failure conditions.

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

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

The description is long but every section carries decision-relevant information: examples, supported types, input constraints, fallback behavior, and endpoint cascading. It is front-loaded with the core purpose and the "Use FIRST" guidance before diving into detail. The heavy use of nested parentheticals makes it dense to parse, but not bloated relative to 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?

With no output schema, the description carries the full burden of explaining return fields, and it does: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, citation, and `unresolved`. It also covers edge cases like non-equity instruments, non-US issuers, ISIN input, and brand/generic drug names. For a two-parameter lookup tool with rich behavior, nothing critical 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?

Even though schema coverage is 100%, the description adds critical meaning beyond the parameter schema. For `value`, it explicitly warns to pass the entity name only, never the question's full noun phrase, and gives a concrete example with "NEW YORK ST DORM AUTH" versus the invalid "NEW YORK ST DORM AUTH revenue bonds." It also explains what each `type` accepts and returns, which materially improves invocation correctness.

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 job — resolving a user-spoken name to canonical identifiers that other tools require — and is packed with concrete example queries. The instruction "Use FIRST whenever you have a name but need an ID" clearly separates it from sibling tools that consume already-resolved IDs. It is specific, actionable, and not merely a restatement of the title.

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

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

The description explicitly states when to use the tool: "Use FIRST whenever you have a name but need an ID." It also explains that it replaces 2-3 manual lookups, which frames it as a preliminary step before other tools. It does not name sibling tools or give explicit when-not-to-use guidance, but the core routing instruction is strong and unambiguous.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by explaining the internal process (probing with ai_visibility_check, ranking) and the output shape (score, confidence, signal density). No contradictions.

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

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

The description is concise with two substantive sentences plus a use-case example. It front-loads the core function (comparison, probing, ranking) and avoids redundancy. Slightly more could be structured, but it is 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?

No output schema, but the description explains return values (ranked list with score, confidence, signal density). It covers the process and purpose adequately for a read-only tool with well-annotated safety profile. Missing details on error handling or limits, but acceptable.

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

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

Schema coverage is 100% and each parameter is described. The description adds context beyond schema: entities array size constraint (2-8), first entity treated as subject, and context parameter is 'shared context'. This provides meaningful guidance for parameter usage.

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

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

The description uses specific verbs 'Compare', 'Probes', 'ranks' and clearly identifies the resource: AI visibility of multiple entities. It distinguishes itself from the sibling tool 'ai_visibility_check' by stating it operates on multiple entities side-by-side and provides ranked results.

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

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

The description explicitly states the use case: 'competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or provide alternatives beyond mentioning it uses ai_visibility_check. Clear context but no exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description enriches this by explaining the fan-out to external sources, partial failures (bundlephobia timeout), and that sources_failed will be listed. 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 slightly long but every sentence serves a purpose. It is well-structured with the main purpose first, then details. Minor reduction possible but 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?

No output schema, but the description thoroughly explains the return value (summary block, details, links) and covers input semantics, defaults, and edge cases (partial failures, ecosystem scope). Complete for a data-gathering tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds context: default version is latest, scoped packages are accepted, which adds value beyond the schema.

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

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

The description clearly states it is a composite check for npm packages covering license, advisories, bundle size, etc. It distinguishes from siblings by specifying the npm ecosystem and noting alternatives for other ecosystems.

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

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

Explicitly tells when to use (when an agent asks about safety, popularity, size) and provides exclusions (PyPI/Maven/Cargo/Go) with a pointer to deps.dev:version.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds value by specifying return fields (dataset_ids, titles, themes, record counts) and how to use IDs with other tools. 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?

Two concise sentences with no fluff. First sentence states purpose and scope, second sentence details return values and usage. Every sentence is valuable, and the description is 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?

Given the tool's complexity (3 parameters, no output schema, good annotations), the description covers purpose, return values, and integration with other tools. It could mention sorting or data source limits, but is sufficient for an agent to use correctly.

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

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

Schema covers 100% parameters with clear descriptions. The description enhances meaning by providing example keyword categories (city services, mobility, environment) and indicating the tool is limited to Issy-les-Moulineaux data. This adds domain-specific context beyond the schema.

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

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

The description clearly states the tool searches Issy-les-Moulineaux Open Data datasets by keyword, with specific categories (city services, mobility, environment & smart-city data). It distinguishes itself from sibling tools like query, dataset_info, and search_within by describing what it returns and how to use the results.

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 by mentioning that dataset_ids can be passed to query/dataset_info, providing integration context. It gives example keywords, but does not explicitly state when not to use this tool or compare to alternatives like search_within. Still, it offers clear guidance for typical use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and return of offsets for verification. This far exceeds what annotations provide.

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 that are front-loaded with purpose, then a clear usage guideline, and finally the technical behavior. No fluff; every clause adds distinct 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 complexity of semantic search, the description covers input constraints (200K chars), embedding model, windowing, scoring, output format (passages with offsets), and a pairing suggestion. No output schema exists, but the description adequately describes return structure. All important aspects are addressed.

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

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

Schema covers all parameters with descriptions (100% coverage). Description reinforces the query parameter as natural-language with examples and notes that passages include offsets for verification, adding context beyond the schema's mechanical definition. Limit defaults are already in schema, but the assistant gains value from the examples and usage framing.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and clearly distinguishes from sibling tools like ask_pipeworx_grounded by specifying that search_within operates on previously fetched text.

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: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, which frames when not to use this tool (grounding over passages vs. whole document). No exclusions are needed beyond this.

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, description reveals account requirement, SMS caps, webhook auto-disable, and that subscription is persisted. IdempotentHint is true but not addressed; 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?

Well-structured with front-loaded purpose, then requirements, types, delivery. Slightly long but every sentence adds value. Could be more terse but effective.

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

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

Covers parameters, requirements, behavior. No output schema but return value is implied. Lacks error handling or subscription limits, but adequate for creation tool.

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

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

Schema coverage is 100%, but description adds valuable examples for each type and detail on delivery parameters (phone verification, webhook signing). Adds significant 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 states the tool creates a proactive monitoring subscription and returns a subscription ID, using specific verbs and resource. It distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and delivery channels. Does not explicitly compare with sibling tools but gives enough for an agent to decide.

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

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral context beyond annotations: it returns example questions, is category-bucketed, and includes tool+argument shapes. There is no contradiction with annotations.

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

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

The description is detailed but well-structured, starting with common natural language queries, then explaining purpose, and ending with usage instructions. Every sentence serves a purpose, though it could be slightly more concise without losing information.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, and return value. It explains what the tool returns (category-bucketed examples with tool+argument shapes) and how to use it, making it complete for its context.

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

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

Schema coverage is 100%, but the description adds meaning by listing example focus areas (finance, pharma, etc.) and explaining the effect of omitting vs. specifying the topic. This provides valuable context beyond the schema's basic description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by positioning itself as the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says 'use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter and when to omit it, providing clear guidance on when to use this tool versus 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?

Discloses that the row is deactivated not deleted and that historical events remain available via recent_alerts, adding value beyond annotations which only indicate non-destructive mutation.

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 wasted words, action and context front-loaded.

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

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

Given the simple input schema and no output schema, the description fully covers purpose, ownership constraint, and side effects.

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

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

Schema coverage is 100% with a clear description of the id parameter; the tool description adds no extra parameter-level detail beyond the schema.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', and differentiates 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?

Provides explicit guidance on ownership enforcement ('you can only cancel your own subscriptions'), implying when not to use it, though doesn't name alternative tools for other cases.

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 read-only/idempotent annotations, the description discloses the internal routing logic (SEC EDGAR fast path vs. grounded pipeline), return verdicts, citation format, and crucially distinguishes 'could_not_verify' (no evidence either way) from 'unsupported' (no source coverage). This is thorough behavioral disclosure.

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

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

The description is lengthy but well-structured: example triggers first, then usage guidance, then behavioral details, then critical caveats. Every sentence adds value, though it could be condensed without loss; it is front-loaded with the most actionable information.

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

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

With no output schema, the description compensates by explaining the full range of verdicts, the meaning of 'could_not_verify' vs 'unsupported', and the citation mechanism. It fully equips an agent to interpret results correctly in all 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% with detailed descriptions for both parameters (claim example, tolerance_pct range, override behavior, default). The description adds no additional semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with natural-language query examples and explicitly states 'natural-language claim verification against authoritative sources.' It clearly identifies the tool's function as verifying factual claims, distinct from siblings by positioning it as a replacement for multi-step pipelines.

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

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

It provides an explicit 'Use whenever' condition for fact-checking and distinguishes behavior for company-financial versus other claims. However, it does not name alternative tools or state when not to use it, falling short of full exclusionary guidance.

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