Remoteok

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

Annotations already declare idempotentHint=true and readOnlyHint=true. The description adds valuable context: explains pricing (free default vs. BYO key for Anthropic) and return structure (per-model fields). It does not mention rate limits or error handling, but overall provides good transparency.

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

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

The description is concise with 4 sentences, each adding essential information: action and score range, default model and apiKey note, return structure, and use cases. No redundant or 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?

Given 4 parameters, no output schema, and moderate complexity, the description provides sufficient detail: mentions return fields (score, confidence, signals, raw_response) and the combined view. It does not cover error scenarios or pagination but is complete for typical 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%, so baseline is 3. The description adds meaning beyond schema by giving examples (e.g., entity examples, context usage) and explaining the _apiKey parameter's role ('passed straight through to api.anthropic.com') and conditionality.

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 ('probe', 'score') and resources ('LLMs', 'visibility') to clearly define the tool's function. It distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI brand visibility scoring.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional apiKey. However, it does not explicitly state when not to use this tool or suggest alternatives.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond annotations: it routes to the correct underlying tool, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No annotation contradiction is present.

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

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

The description is long but information-dense and front-loaded with the crucial 'PREFER OVER WEB SEARCH' directive. The domain list and examples earn their place by clarifying scope, though the text could be slightly tightened without losing meaning.

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

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

Given there is no output schema, the description adequately explains the return behavior: a structured answer with stable citation URIs. It also covers routing logic and sibling alternatives, making it sufficient for an agent to select and invoke the tool. Exact response shape and failure behavior are not detailed, preventing a perfect score.

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 all six parameters are documented as aliases for the question, so the description does not need to repeat parameter mechanics. It adds value with example phrasings and lists of query triggers, which helps an agent formulate a valid natural-language question for the single required 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 names a specific action — routing a natural-language question to one of 5,738 tools across verified sources and returning a structured answer with citation URIs. It clearly distinguishes ask_pipeworx from web search and from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual/current/historical questions, and includes trigger phrases plus concrete examples. It also states when NOT to use it, directing claim verification to ask_pipeworx_grounded and broad multi-part fan-out to deep_research.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond those: it discloses the experimental beta nature, that routing improvements are active only when under test, that none is currently active, and that it is a full working router rather than a fallback stub. This is exactly the kind of behavioral nuance an agent needs when choosing between beta and stable variants.

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

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

The description is a single compact paragraph that front-loads the core identity ('Beta version of ask_pipeworx') and quickly moves to what is identical, current behavior, and usage. The exact date and tool count add specificity without bloating the text. Slightly dense, but 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?

For a beta tool with dynamic routing candidates, the description covers all essential context: what it is, how it differs from the stable version, whether a candidate is currently active, how to invoke it, and that it is a fully functional router. Even without an output schema, it addresses the return shape by stating it matches ask_pipeworx. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and aliases. The description adds only the cross-tool reassurance that it takes 'the same arguments' as ask_pipeworx, which is useful but not necessary for understanding the parameters. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx and explicitly distinguishes it as an identical universal router with the same 5,738 tools, arguments, and response shape. It goes beyond a tautology by explaining exactly what the tool does and how it relates to its stable sibling.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state of no active candidate and that results are compared against the stable router. It does not explicitly state when not to use it or mention grounded alternatives, but the context is clear.

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

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

Beyond the readOnly/openWorld/idempotent/non-destructive annotations, the description discloses the full success contract, the structured refusal behavior with refusal_reason enumerations, the evidence extraction guarantee, and the extra LLM-call cost. 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: identity, routing, extraction guarantee, return/refusal contracts, use cases, and cost tradeoff. It is front-loaded with the critical grounded-answer distinction before the longer behavioral details.

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 high-stakes read tool with no output schema, the description fully documents the success and refusal return shapes, the use-case boundaries, cost behavior, and sibling routing. An agent has everything needed to invoke it correctly and interpret failures.

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

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

Schema description coverage is 100% and the only parameter, question, is already documented with natural-language semantics and aliases. The tool description adds routing context but no additional parameter meaning, so the baseline of 3 applies.

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

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

The description opens with a specific, differentiated purpose: it is a hallucination-resistant, grounded answer mode for high-stakes reads. It clearly names the resource and distinguishes itself from the sibling ask_pipeworx by its extraction behavior, so an agent can select this tool without ambiguity.

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?

Use is explicitly prescribed: when an answer will be quoted, cited, or acted on, and the agent must not invent facts, with concrete examples. It also gives the when-not-to-use case, recommending ask_pipeworx for casual lookups for cost reasons.

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

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

The description goes far beyond the annotations, detailing extensive behavioral traits: market resolution, classification, fan-out to data sources, response shapes, resolver contract, parent event extraction, news field fallbacks, safety behaviors for low-confidence matches, closed markets, wide spreads, and cancellation rules. This provides full transparency without contradicting 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 comprehensive but lengthy, spanning multiple paragraphs with many technical details. It is well-structured with headers and examples, but could be more concise while preserving key information. Some redundancy exists (e.g., repeating classifiers list).

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 data sources, response structures, edge cases) and the absence of an output schema, the description provides thorough coverage of all relevant aspects: input handling, classification, fan-out examples, response fields, safety mechanisms, and special cases like closed markets and cancellation rules. This enables an agent to use the tool effectively.

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

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

Although the input schema has 100% coverage, the description adds practical meaning: for 'market' it explains accepted formats (slug, URL, question text); for 'depth' it defines 'quick' vs 'thorough' with defaults; for 'include_raw' it clarifies when to use true. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and provides examples of use cases. This distinguishes it from sibling tools, which are more general or focus on different tasks.

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

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

The description provides explicit use cases such as 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. It also explains input formats (slug, URL, question text). However, it does not explicitly state when to use alternatives or when not to use this tool, which would strengthen the guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant behavioral detail: for companies, it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, it pulls FAERS, FDA approval counts, and trial counts. It also notes sorting by primary metric and returns paired data with citation URIs, going beyond annotations.

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

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

The description is a single dense paragraph but front-loaded with trigger phrases and key information. Every sentence adds value, though breaking into sub-sections could improve scanability. It is concise and efficient.

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

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

Given the tool's complexity (comparing up to 5 entities, two types, multiple metrics), the description covers what it does, when to use, specific data sources, sorting behavior, and return format (paired data + citation URIs). No output schema exists, but the description sufficiently describes the output scope, making it complete 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?

Input schema has 2 parameters with 100% coverage, but the description adds semantic value: for 'values', it gives examples of tickers/CIKs and drug names, and specifies min/max items. This provides context that the schema alone does not, such as the format of values for each entity type.

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: side-by-side comparison of 2–5 companies or drugs with specific metrics per type. It includes trigger phrases like 'X vs Y' and 'compare', and distinguishes itself from sibling tools like entity_profile by explicitly noting it replaces multiple 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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also implies not to use for single entity lookups, and explains it replaces 8–15 sequential lookups, reinforcing the use case.

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

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

Beyond the annotations, the description discloses authentication requirements, paid depth tier, latency expectations, output shape including gaps[], contradictions[], hop fields, citation_uri fetchability, and the fact that findings are never invented. This is rich, decision-relevant behavioral context and it is consistent with the readOnly, idempotent, and non-destructive 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: every sentence carries decision-relevant information such as account requirements, sibling routing, output semantics, citation guarantees, and expected latency. It is front-loaded with the most critical operational constraint (account required) before explaining the tool's 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?

For a complex tool with no output schema, the description comprehensively covers what results look like, how gaps are handled, when contradictions appear, how citations resolve, and how long calls take. An agent has everything needed to decide when to call it, set expectations, and interpret the response.

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

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

Schema description coverage is 100%, so the input schema already fully documents the question parameter and the depth enum with facet counts, hop behavior, and paid tier. The description mostly restates these details rather than adding new parameter-level meaning, so it meets the high-coverage baseline but does not substantially extend it.

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

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

The description states a precise verb and resource: grounded multi-source research over 1499 structured data sources via parallel decomposition. It is clearly differentiated from siblings by naming ask_pipeworx as the alternative for single lookups and current news, and by explicitly stating 'this is NOT open-web search.'

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

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

It gives explicit when-to-use guidance: broad/multi-part questions over structured data, with concrete examples. It also gives explicit when-not-to-use guidance: single lookups and current-news topics should go to ask_pipeworx, and unsigned-in users are routed to ask_pipeworx as the fallback.

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

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

Annotations indicate read-only and idempotent, and the description adds behavioral details like returning 'top-N most relevant tools with full input schemas' and 'ready to call directly'. No contradiction.

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

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

Description is well-structured and front-loaded with the core action. While fairly long, each sentence adds necessary detail without redundancy.

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

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

Despite lacking an output schema, the description sufficiently explains what is returned: tool names, descriptions, and schemas. Covers key aspects like aliases and limit, though could mention pagination or error handling.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by providing real-world examples (e.g., 'look up FDA drug approvals') and explaining the natural language intent, 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 'Find tools by describing the data or task' and enumerates many domains, making the tool's purpose highly specific and distinguishing it from sibling tools like search_jobs.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial non-obvious context: fan-out is parallel and consolidated in one call, sources_used/sources_failed signal real no-data results, an empty fda_products section is expected for small-molecule-only companies, news uses GDELT→GNews fallback, and private companies return resolved:false with an explicit notes line instead of a bare failure. No contradiction with annotations.

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

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

The description is long but information-dense, and every clause carries operational meaning. Examples and the priority directive are front-loaded, though the body is one sprawling paragraph with many parentheticals; slight restructuring into bullets would improve scanability without losing content.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values. It enumerates the result sections (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/sources_failed), explains URI formats, and covers edge cases like expected empty FDA results and private-company behavior. This is complete enough for an agent to call and interpret the tool reliably.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond by explaining that type values "company" and "ticker" are interchangeable and accept the same value shapes, that names resolve via SEC EDGAR company-name match, and that results include resolved_from/resolved_to when a name was supplied. This adds real semantic guidance beyond the schema.

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

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

The description opens with concrete user intents like "Tell me about X" and "company profile for Microsoft," then defines the operation as a "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes this from single-source lookup chains by naming the fan-out across SEC, XBRL, patents, contracts, FDA, hiring, news, and GLEIF.

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 says "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view," giving a direct when-to-use instruction and naming the alternative approach. It also clarifies accepted inputs and how private-company results behave, so an agent knows when this tool will fail gracefully rather than error.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description restates 'delete' but adds no new behavioral traits beyond the obvious. The 'clear sensitive data' note is more usage context than 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?

Two sentences, no fluff. Each sentence earns its place: first defines action, 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?

Tool is simple (1 param, no output schema). Description covers purpose, usage, and context. Could mention absence of return value or confirmation, but acceptable given simplicity.

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

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

Schema coverage is 100% with 'key' property described as 'Memory key to delete'. Description does not add semantic value 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?

Clearly states 'Delete a previously stored memory by key.' The verb-resource pair is specific and unambiguous. Mentions sibling tools 'remember' and 'recall', differentiating its role.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Includes pairing advice with 'remember' and 'recall', guiding agent on alternative tools.

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

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

Discloses that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', adding context beyond the readOnlyHint and idempotentHint annotations. However, it does not mention potential limitations like rate limiting or page access restrictions.

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

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

Three concise sentences that front-load the purpose, then detail the process and use cases, with no redundant or vague phrasing.

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?

Adequately covers the tool's behavior and output format given the simple schema and annotations. Could mention that it only works for publicly accessible pages or cite output format details, but overall 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 description coverage is 100%, so the description adds little new meaning beyond the parameter descriptions. It mentions 'max_links' default and max, but this is already in the schema.

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

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

The description clearly states the verb 'Generate' and the resource 'production-ready llms.txt file', and specifies the distinct purpose of enabling AI crawlers to index a site. It differentiates from sibling tools like 'ai_visibility_check' by focusing on file generation.

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

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

Provides explicit use cases (getting client's site indexed, drafting llms.txt, auditing competitor) but does not mention when to avoid this tool or suggest alternatives among siblings.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds value by specifying that the response includes full HTML description and salary in USD when present. No contradictions.

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

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

Three concise sentences with no fluff. Each sentence adds meaningful information: what the tool does, how to get the id, and a limitation.

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 single-parameter retrieval tool with no output schema, the description covers the returned content (full HTML, salary) and availability constraint. It is adequately 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 covers 100% of parameters with a clear description. The description adds that ids come from sibling tools, which is slightly helpful but not essential. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves the full RemoteOK job posting for a given id, including HTML description. It distinguishes from sibling tools like list_jobs and search_jobs by specifying the unique function.

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 to use ids from list_jobs or search_jobs, and notes the limitation of only recent ~100 listings. It could mention scenarios where the tool is not appropriate (e.g., for historical jobs), but the guidance is clear and helpful.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specifics: returns only recent postings with selected fields, no HTML description, and salary behavior (USD, 0=undisclosed).

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

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

Two sentences: first states purpose and source, second details returned fields and salary. Front-loaded, no wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, source, return fields, and salary nuances. No gaps.

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

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

Schema describes the single optional 'limit' parameter with default and max. Description does not add beyond this, so baseline score of 3 for high schema coverage (100%) is appropriate.

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

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

The description clearly states the tool lists the most recent remote jobs from RemoteOK, a specific source. It is distinct from sibling tools like search_jobs (filtered search) and get_job (single job).

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

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

The description implies usage for broad listing of recent jobs, but does not explicitly state when to use it versus alternatives like search_jobs. No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing specific return fields and clarifying that it lists active subscriptions, with an optional parameter for inactive ones. 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 two sentences, front-loaded with the core action and return fields, followed by usage guidance. No extraneous words; every sentence earns its place.

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

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

Given the simple input schema (one optional param), rich annotations, and no output schema, the description fully covers the tool's purpose, return fields, and usage context. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the single parameter (include_inactive, with description). The description does not add additional parameter details, but given high coverage, a baseline score of 3 is appropriate.

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

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

The description clearly specifies the verb 'List' and resource 'subscriptions', and explicitly mentions the return fields (id, type, params, created_at, last_fired_at, fire_count). This differentiates it from sibling tools like subscribe and unsubscribe.

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

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

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

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

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

Even though annotations are all false (readOnlyHint=false, etc.), the description goes beyond them by disclosing rate limits (5/day), cost (free, no quota), and the claim_token flow for tracking submissions. It explains the team's review cadence and that signal affects roadmap, giving the agent a fuller picture of consequences.

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

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

The description is longer than average, but every sentence earns its place: purpose, exclusions, claim_token mechanics, rate limit, and quota policy. It is front-loaded with the core purpose and then flows logically. A slight deduction for some motivational phrasing ('signal directly affects roadmap') that is not strictly necessary.

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 relative simplicity and lack of an output schema, the description is thorough. It covers what the tool does, when to use it, when not to, the claim_token return value, how to read a later response, rate limits, and cost. Nothing important is left ambiguous for an agent deciding to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving a concrete usage example for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by advising users not to paste the end-user's prompt, which clarifies the expected message content.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling research/prediction tools by framing it as feedback about the Pipeworx connection itself, not a data-querying 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 when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and a clear exclusion: if the tool is from a different MCP server, report it there instead. It also tells users how to identify Pipeworx tools when unsure, which is exactly the kind of alternative-selection guidance needed.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description goes beyond by explaining the data source (CF analytics-engine), that no PII is used, and the caching window (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?

Three sentences, each purposeful: output overview, use cases, transparency details. No redundant or vague language.

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 fully explains what is returned (top tools, top packs, total call volume). Caching behavior is disclosed. For a simple read-only tool with one optional parameter, this is complete.

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

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

Schema coverage is 100% for the single parameter. The description adds semantic value by explaining that shorter windows surface current hotness and longer windows show steady-state demand.

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

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

The description opens with a clear statement of what the tool returns ('top tools, top packs, and total call volume') and specifies the context ('What other AI agents are calling on Pipeworx right now'). This distinguishes it from sibling tools like discover_tools or search_within.

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

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

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't explicitly state when not to use it, the context is clear enough for an agent to decide.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) indicate safety and idempotence. The description adds extensive behavioral context: algorithms used, semantic anchor (Jaccard similarity), partition filter, fill check against live CLOB depth, and response structure. 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 fairly long but well-structured: a clear one-sentence summary followed by mode-specific paragraphs. It is front-loaded with the core purpose. Some redundancy exists (e.g., repeating 'event (recommended...)'), but overall it's organized and readable.

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

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

Despite no output schema, the description details the response structure (opportunities[], partition_check fields, fill check result). It covers all behaviors, prerequisites, and warnings. For a tool with two optional parameters, the description is remarkably 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 covers both parameters (event, topic) with descriptions. The description adds significant extra guidance: examples of event slugs and topic seed questions, accepted URL format, and explanation of modes. With 100% schema coverage, baseline is 3; the added value merits a 4.

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

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

The description states the tool's purpose clearly: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and explains each. It also references sibling tools like polymarket_fill_risk, providing differentiation.

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

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

The description explicitly tells when to use each mode: no args for trending scan, event for per-event, topic for cross-event. It recommends 'event (recommended for a specific market)' and explains cross-event mode advantages. It also warns when not to trade: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.'

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

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

The description extensively details internal logic: model families (crypto_price, news_momentum, etc.), edge calculations, segments (by_segment), diagnostics, and caching (1h KV-level). This goes well beyond the annotations (readOnlyHint, etc.) and provides full behavioral transparency without contradictions.

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

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

The description is lengthy and dense with technical details, formulas, and edge cases. While every sentence adds value, the structure is a single large paragraph that could be better organized (e.g., using bullet points for segments or knobs).

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 (9 parameters, no output schema, nested objects), the description thoroughly explains the output structure (by_segment, fed_candidates, diagnostics) and internal logic. It compensates for the missing output schema by describing return fields in detail.

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 does not add much parameter-level meaning beyond the schema; it focuses on overall tool behavior. It briefly mentions 'tradeable-edge knobs' but does not elaborate on individual parameter semantics.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It provides a specific verb ('Scan') and resource ('Polymarket markets'), and the purpose ('what should I bet on today') distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description implies usage for discovering betting opportunities without paging, and mentions caching and knobs. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide when-not-to-use guidance or compare with siblings.

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

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

Adds behavior beyond annotations: explains history bounded by 60-day TTL, snapshot gaps on cache-miss, decay from daily closes not intraday, and response structure. Complements readOnlyHint and idempotentHint.

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

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

Long but well-structured with clear sections for purpose, args, response, and limits. Every sentence provides value; slightly dense but appropriate for the tool's complexity.

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

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

No output schema, but description fully covers return fields (tracked, expired, snapshot_dates) with detailed subfields. Explains limits and edge cases like gaps. Completely sufficient for the 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%, baseline 3. Description adds context: days default 14, clamp 2-30, window as 'snapshot family' with examples, 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?

Description clearly states the tool provides edge persistence and decay telemetry from snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on historical trends.

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?

Implies usage for assessing edge age and decay with example of fresh vs. old wide edges. Does not explicitly list alternative tools or when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context beyond annotations: it 'walks the ladder', specifies clamping on size_usd (10–1,000,000), and warns about forced_directional_risk. 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: header summary, requirements (market|event), mode details (SINGLE-MARKET and BASKET sections), then usage guidance. Every sentence is informative; no filler or redundancy.

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

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

No output schema, so description must cover return values. It does: for single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, etc.). Also explains key risks (thin_legs, forced_directional_risk). Fully adequate given complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds: for single-market, size_usd is 'max spend on buys, target proceeds on sells'; for basket, it's 'settlement notional — shares per leg'. It also explains side default for basket (auto based on partition sum). Adds value beyond schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return values for each mode, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why, citing risks of thin books and partial fills converting arb to unhedged positions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavior: it does not model Kalshi's fee schedule, reported spreads are gross rather than net tradeable edges, unmatched legs land in skipped_unclassified, warnings can be non-empty even when pairs are returned, and temporal_alignment=null means unknown rather than aligned. This is far more transparency than the annotations alone 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?

The description is long but well-structured with clear label segments: TWO MODES, RESPONSE, SAFETY FIELDS, and codes. It front-loads the core purpose and mode choice before diving into safety details. There is some redundancy around 'EITHER mode' and repeated warnings, which prevents a perfect score, but no sentence is filler given the absence of an output schema.

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 and three optional parameters, the description carries the full burden of explaining response semantics, safety flags, compatibility codes, skipped counters, fee-treatment caveats, and temporal alignment behavior. An agent has enough information to call the tool correctly, interpret its results conservatively, and avoid treating raw spreads as tradeable edges.

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 semantic value by explaining the mode relationship: `topic` auto-fetches matching events, explicit tickers override the mapped side, and both modes feed the same token-overlap matcher. It also enumerates all recognized topic shortcuts, supplementing what the schema already lists.

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

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

The opening sentence names a specific operation and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also flags the scope and the key caveat that the delta is only a real signal when bet shapes are equivalent, which distinguishes this from generic arbitrage or edge tools in the sibling list.

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

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

The description clearly defines two mutually exclusive calling modes — `topic` for pre-mapped macros and explicit ticker/slug for custom pairings — and says both run the same matcher. It also warns that most pre-mapped topics currently return a compatibility warning and that pre-mapped does not mean tradeable, which is actionable guidance. It does not explicitly contrast with sibling tools like polymarket_arbitrage, so it stops short of a 5.

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

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 value by explaining the listing behavior when key is omitted, scoping to identifier, and pairing with related tools, with 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 two sentences, front-loaded with the primary action, and every sentence adds value 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers its purpose, usage, parameter behavior, and scope, making it complete.

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

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

The input schema has 100% coverage for the one optional parameter. The description adds 'omit the key argument to list all keys', providing additional semantics beyond the schema's 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 explicitly states 'Retrieve a value previously saved via remember, or list all saved keys', using a specific verb and resource. It clearly distinguishes from sibling tools remember and forget by naming them.

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

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

The description provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains scoping and pairs with remember/forget, though it does not explicitly state when not to use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it explains that setting mark_read=true flags events as read and that the same feed is accessible via a REST endpoint. It does not contradict annotations; the additional context enhances understanding of side effects (e.g., mark_read modifies state).

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

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

The description is a single paragraph that efficiently conveys key information: purpose, return fields, filters, and an alternative endpoint. It is front-loaded with the main action. Though slightly lengthy, every sentence adds value and there is 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 thoroughly explains return fields (source, citation_uri, raw payload) and covers all parameter behaviors (filtering, mark_read, unread_only). It also provides an alternative access method for scripts and dashboards, making the tool's role in the ecosystem clear. This is highly complete for a read-only polling 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 the baseline is 3. The description adds meaning beyond the schema by providing examples (e.g., 'sec_8k' for type) and clarifying that 'since' is an ISO timestamp and that 'unread_only' returns events with null read_at. This helps the agent understand parameter usage beyond the schema descriptions.

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

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

The description starts with a clear verb-resource pair ('Pull fired events from your subscription feed') and specifies what each returned alert contains (source, citation_uri, raw payload). It distinguishes itself from other tools by mentioning an alternative access method for scripts and dashboards, making its specific role clear.

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

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

The description explains when to use the tool (to get recent alerts, with optional filters) and provides explicit details on filtering parameters (type, since, mark_read, unread_only). It also mentions that polling works fine and gives an alternative endpoint, but does not explicitly state when not to use it or compare directly with siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which the description complements by detailing the fan-out behavior, fallback from GDELT to GNews on rate limits or 5xx, and the USPTO soft-failure. No contradictions; the description adds valuable behavioral context beyond annotations.

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

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

The description is a single paragraph with no wasted sentences, front-loading usage examples. It could be more structured (e.g., bullet points) but remains concise given the amount of information conveyed.

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

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

Despite no output schema, the description clearly states the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It also covers constraints (only company type, USPTO soft-failure). For a 3-parameter tool, this is complete and sufficient for an AI agent to understand what to expect.

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

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

Schema description coverage is 100%, but the description still adds meaning: it explains the 'since' parameter format (ISO date or relative shorthand) and suggests typical values, clarifies 'type' only accepts 'company', and gives examples for 'value'. This adds marginal but useful extra information beyond the schema.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists the sources (SEC EDGAR, GDELT→GNews, USPTO). It differentiates from sibling tool 'entity_profile' by directing to use the latter for static profiles. This is a specific verb+resource with clear scope and sibling distinction.

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

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

The description provides explicit usage examples like 'What's new with X' and 'latest on Y', tells when to use (any question about recent changes) and when not to (use entity_profile for static profiles). It also gives parameter guidance: 'Use "30d" or "1m" for typical monitoring'. This is comprehensive guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds crucial behavioral details: scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. 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 one well-structured paragraph. It front-loads the core purpose, follows with usage guidance, then details. Every sentence adds value without redundancy. Excellent conciseness.

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

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

For a simple tool with 2 params, full schema coverage, annotations, and no output schema needed, the description covers all necessary context: purpose, when to use, behavioral details (scoping, retention), and links to complementary tools. No gaps.

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

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

Schema covers both parameters with clear descriptions and examples (100% coverage). The description adds context about scoping but doesn't significantly augment the schema's semantic clarity. Slight value from 'key-value pair scoped by your identifier.'

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: 'Save data the agent will need to reuse later.' It specifies the action (save), the resource (data), and the context (across conversation or sessions). It distinguishes itself from siblings like recall and forget by describing its complementary role.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward.' Provides examples of what to store (ticker, address, preference). Directs to pair with recall and forget, offering clear usage guidance. No exclusion criteria needed given the simplicity.

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

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

Annotations already mark the tool as read-only/idempotent, and the description adds substantial behavioral detail: cascading internal lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, ambiguity handling via figi_candidates, explicit unresolved identifiers, source labelling, and ISIN-to-LEI mapping. No contradictions.

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

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

The description is front-loaded with query templates and a clear 'Use FIRST' directive. It is long and dense, especially the company-type parenthetical, but nearly every segment adds operational value; it could be tightened 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 two-parameter tool with no output schema, the description covers input constraints, ambiguity behavior, unresolved-identifier handling, source labelling, and error degradation. It does not provide a full return-shape specification, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

Even though schema coverage is 100%, the description adds crucial operational rules: pass only the entity name, avoid trailing security-class words for bonds, ISINs resolve to legal entities, and drug lookups return RxCUI plus ingredient and brand. The value-parameter guidance is materially richer than the schema.

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

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

The description opens with concrete user utterances and states explicitly that the tool resolves user-spoken names to canonical/official identifiers required by other tools. It differentiates itself from siblings like entity_profile or compare_entities by framing itself as the identity-lookup step.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported entity types and provides example queries. It does not name sibling alternatives or state when not to use it, but the usage context is unmistakable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the process (probes each entity with ai_visibility_check, ranks results) and output format, without contradicting annotations.

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

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

Three sentences front-loaded with purpose, followed by method and example. No filler or redundancy; every sentence serves a purpose.

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

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

Given the tool complexity (4 params, no output schema), the description covers core functionality, use case, and output format. Lacks mention of array size limits (though schema states 2-8) and error scenarios, but sufficient for typical usage.

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

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

Schema description coverage is 100%, but the description adds meaningful context: treats first entity as 'subject', explains when _apiKey is needed, and clarifies 'context' parameter usage. This goes beyond the schema definitions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, with a specific verb 'compare' and resource 'AI visibility'. It distinguishes from the sibling tool 'ai_visibility_check' by noting it probes each entity and returns a ranked list, making its comparative purpose evident.

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 provides a use case 'competitive AI-marketing audits' and an example question. It implies when to use (side-by-side comparison) but does not explicitly state when not to use or directly differentiate from sibling 'compare_entities', though the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia timing delay, and sources_failed field. This goes beyond annotations, earning a 4.

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 well-organized, covering purpose, usage, behavior, and output in one paragraph. Could benefit from bullet points for readability, but it is appropriately sized and 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?

No output schema exists, but the description explains the output structure (summary block, per-advisory detail, links, alternatives). It also mentions partial failures and ecosystem scope. This is fairly complete for a complex 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 description coverage is 100%, so baseline is 3. The description adds that version defaults to latest, but package parameter details are already in schema. No significant additional meaning beyond schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package to a project, covering license, advisories, version history, and bundle size. It distinguishes from siblings by explicitly limiting to NPM ecosystem and mentioning alternative tools 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 states when to use the tool, such as when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies limitations (NPM only in v1) and directs to deps.dev:version for other ecosystems.

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. The description adds value by specifying case-insensitive matching, the fields returned, and that salaries are in USD. This extra context is 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?

Three efficient sentences. First sentence states purpose and matching scope. Second adds context (tech-heavy, keyless). Third lists return fields and currency note. Every sentence earns its place with no redundancy.

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

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

No output schema exists, so the description compensates by listing return fields (id, position, company, etc.) and noting salary currency. It lacks pagination or error info, but for a simple keyword search tool with clear annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, baseline 3. The description enhances meaning for 'query' by explaining it matches against position, company, or tags (case-insensitive), which adds detail beyond the schema's description. The 'limit' parameter default is in schema, but no extra info in 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 states a specific verb and resource: 'Keyword-search current RemoteOK remote-job listings'. It clearly distinguishes from siblings like list_jobs (which likely returns all) and get_job (which gets by ID), as it focuses on keyword matching against position, company, or tags.

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 clear context for usage: 'Tech-heavy board; keyless' implies no authentication needed and the domain. It does not explicitly list when to use vs alternatives like list_jobs or get_job, but the keyword search scope is well-defined.

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

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

Describes behavioral traits beyond annotations: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K char cap with truncation flag. Annotations already indicate safe, idempotent, open-world behavior, and description adds valuable context without contradiction.

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

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

The description is a single, well-structured paragraph of 5 sentences. The first sentence front-loads the core function. Subsequent sentences add examples, use cases, and technical details. Every sentence contributes valuable information without redundancy.

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

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

Despite no output schema, the description adequately explains the return format (top-N passages with offsets and similarity scores). It covers purpose, usage, behavior, parameters, and output. For a tool with 3 fully described parameters, the description is complete and actionable for an AI 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%, with each parameter having a description. The description adds additional meaning: for 'text' it clarifies the ~200K char limit, for 'query' it gives example queries, and for 'limit' it specifies range and default. This enhances understanding beyond the schema.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, using specific verbs and resource. It provides concrete examples (SEC 10-K, article, long tool result) and distinguishes itself from sibling tools by mentioning its pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. It outlines the benefit (saves context, returns relevant passages) and contrasts with asking the whole document. Also provides guidance on pairing with a sibling tool.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds critical behavioral details: OAuth requirement, always-on feed, optional delivery channels with verification and rate limits, webhook signing secret one-time return, and auto-disable after failures. This fully informs the agent about side effects and constraints.

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

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

The description is comprehensive but slightly lengthy. It uses well-structured bullet points for types and delivery channels, front-loading the core action. A bit more conciseness could be achieved, but it remains efficient.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers all essential aspects: authentication, type-specific filters, delivery options with limitations, and behavioral traits like one-time webhook secret. It leaves no critical gaps for an AI 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%, but the description adds extensive value: detailed examples for each type in params, constraints for delivery fields (e.g., E.164 phone, webhook HTTPS only), and clarification of required fields (sponsor or condition for clinical_trial). This far exceeds 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by detailing the creation aspect and return of subscription ID.

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

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

The description provides explicit context: requires Pipeworx OAuth account, lists supported types and delivery channels, and mentions constraints (e.g., 10/day SMS cap, webhook auto-disable). It does not explicitly exclude use cases but offers enough guidance for correct invocation.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns category-bucketed examples with exact tool+argument shapes, providing helpful behavioral context beyond annotations.

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

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

The description is slightly long but well-structured, opening with common user questions and then detailing behavior. Each sentence adds value, though some redundancy exists with the alternative phrasings.

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

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

For a tool with one optional parameter and no output schema, the description fully explains what is returned (example questions, tool+argument shape) and when to use it, making it contextually complete.

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

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

Schema coverage is 100% with a single optional parameter described as 'Optional focus area'. The description enriches this by listing valid topic values and clarifying that omission yields a cross-category spread.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and lists exact topics, distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly states when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also describes how to focus with the topic parameter and mentions learning about meta-tools.

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

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

The description adds that the row is deactivated not deleted, and historical events remain via recent_alerts. Annotations already indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true), so the description enriches with specific behavior beyond annotations.

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

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

Two concise sentences: first states the core action, second adds ownership and deactivation details. Front-loaded and efficient with zero waste.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership constraint, and side-effect (deactivation not deletion). Nothing 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?

With schema coverage at 100% and only one parameter 'id' described as 'Subscription id (uuid) returned by subscribe,' the description adds no additional semantic value beyond the schema. Baseline 3 applies.

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

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

The description starts with 'Cancel a subscription by id,' clearly stating the verb (cancel) and resource (subscription by id). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It specifies 'Ownership is enforced — you can only cancel your own subscriptions,' providing a clear constraint. While no explicit alternative or when-not-to-use is given, the ownership rule gives practical 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?

Beyond the non-destructive/read-only annotations, the description discloses the fast-path versus grounded pipeline selection, the exact meaning of 'could_not_verify' (with verification_error), and 'unsupported', plus an explicit caller warning that could_not_verify must not be presented as evidence. This greatly exceeds annotation coverage and exposes potential pitfalls.

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 sentence carries weight: trigger phrases, usage rule, pipeline routing, return semantics, and the critical edge-case warning. It is layered logically and front-loads the purpose, achieving high information density with zero filler.

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

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

With no output schema, the description fully enumerates the verdict set and clarifies the nuanced distinction between could_not_verify and unsupported. It covers both execution paths and even explains the tolerance math rule, making the tool self-contained for an agent to invoke and interpret results correctly.

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

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

The input schema already provides 100% coverage for both parameters with detailed descriptions and examples, which sets the baseline at 3. The description adds no new parameter-level detail; it only re-emphasizes the percent-delta math already covered by the schema. This is adequate but not additive.

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

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

The description opens with concrete trigger phrases ('fact check', 'verify the claim that…') and states the exact function: natural-language claim verification against authoritative sources. It differentiates the two execution pipelines (SEC/XBRL for financial, grounded for all else) and lists the output verdicts, making the purpose unmistakable and distinct from sibling ask/verify tools.

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

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

It gives an explicit when-to-use rule: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for financial vs non-financial claims. However, it does not name specific sibling tools to prefer instead or list exclusions, so it lacks the when-not-to/alternatives dimension of a full 5.

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