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 convey readOnly, openWorld, and idempotent hints. The description adds substantial behavioral context: it routes to 5,529 tools, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and handles live news. This supplements the annotations without contradiction.

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

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

The description is longer than average but densely packed with necessary guidance: usage categories, examples, alternatives, and default positioning. It front-loads the key directive ('PREFER OVER WEB SEARCH') and every sentence earns its place, though a slight trim could be made without loss.

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

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

For a broad router tool with no output schema, the description is complete: it explains what the tool returns (structured answer with citations), when to use it, when to use alternatives, and provides examples across domains. It also notes performance characteristics ('one fast call'), covering the agent's selection and invocation needs.

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

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

Schema description coverage is 100%—all six parameters are documented as aliases for the natural-language question. The description adds examples of good questions and reinforces the 'question' parameter, but provides no parameter-format detail beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it routes factual questions to the appropriate tool among 5,529 tools across 1,455 sources and returns structured answers with citations. It explicitly distinguishes itself from siblings ask_pipeworx_grounded and deep_research, and positions itself as the default 'START HERE' entry point.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a comprehensive list of domains, and it names alternatives with specific scenarios—ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. It also covers breaking news and 'what's the world saying' use cases, making selection criteria 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it is a full working router that 'falls back to nothing' and that candidate routing improvements are enabled live when under test, informing the agent about potential behavior variability and the experimental nature.

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

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

The description is three sentences, front-loaded with the core identity, then adding current state and usage guidance. Every sentence contributes unique information without redundancy, keeping it succinct while informative.

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

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

The description clarifies its relationship to ask_pipeworx, current behavior (matches stable when no candidate is active), and usage instructions. It references the same response shape as ask_pipeworx, which compensates for the missing output schema, though it does not discuss edge cases or error behavior. The annotations adequately cover the safety profile.

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 described as an alias for 'question,' and the question parameter includes the full semantic description. The tool description does not add new parameter details beyond stating it accepts the same arguments as ask_pipeworx, so the schema carries the parameter documentation burden.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable sibling by its experimental routing improvements, making its purpose and unique scope explicit.

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 instructs users to 'use it exactly like ask_pipeworx when you want the newest routing,' providing a clear use case. It also mentions that results are compared against the stable router to decide what merges, implying a testing/feedback role, though it does not explicitly say when not to use it (e.g., for production stability).

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 by detailing the exact return format (e.g., `{answer, evidence, confidence, source, fetched_at, refusal_reason}`), the explicit refusal reasons (`not_in_source`, `no_tool_match`, etc.), and the guarantee to use ONLY the tool result. It also discloses the extra LLM call cost. None of this contradicts the annotations (readOnly, openWorld, idempotent, non-destructive).

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 adds value: purpose, mechanism, return structure, refusal reasons, usage guidance, and cost/alternative. It is front-loaded with the main distinction and flows logically. No filler or redundancy; it earns its length.

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

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

Despite having no output schema, the description fully explains return values and refusal behavior, making the tool's behavior predictable. It also provides sufficient context for high-stakes use cases and comparisons with sibling tools, making it complete for an AI agent to select and invoke correctly.

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

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

The input schema has 100% coverage: all six parameters are documented as aliases for `question`, and `question` has a clear description. The tool description does not add parameter-level semantics beyond what the schema already provides, so a baseline score of 3 is appropriate. It does not need to repeat schema info.

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

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

The description opens with a specific and distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the tool's behavior (picks tool, fetches data, extracts answer using only the result) and explicitly differentiates from the sibling `ask_pipeworx` by noting 'Same routing as ask_pipeworx' but with added extraction and refusal logic.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also states when not to use it and names the alternative: 'prefer ask_pipeworx for casual lookups.' Additionally, it mentions the cost trade-off (one extra LLM call), helping the agent weigh usage.

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

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

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?

Goes well beyond the readOnly/openWorld/idempotent annotations. Discloses that findings include gaps[] for unanswered facets, that it 'never invented' data, how second-hop iteration works at different depths, the contradictions[] scan, semantic excerpting of large records, and expected latency. Also explicitly notes it is NOT open-web search, which is crucial context. 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 front-loaded with the critical account warning and high-level purpose. While some operational details could be trimmed, every sentence contributes context about behavior, alternatives, or data characteristics. The structure flows from prerequisites to usage guidance to technical 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?

Given there is no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), latency expectations, and the meaning of hop/citation_uri. It also covers prerequisites, alternatives, and limitations, making it sufficiently complete for an agent to invoke it correctly.

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

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

The schema already provides detailed descriptions for both parameters, especially depth with its enum and meaning. The description adds further nuance by explaining how depth values affect facet counts ('quick=3 ... standard=5 ... thorough=8') and the gap-recovery behavior, enriching the schema's structural descriptions.

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

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

The description clearly states the tool performs multi-source structured research ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources') and explicitly distinguishes it from sibling tools by contrasting with ask_pipeworx for single lookups and current news. The verb 'research' plus the resource scope make the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use with alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'). Also notes the account requirement and redirects signed-out users to ask_pipeworx.

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

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

Annotations 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?

The description discloses behavioral traits beyond annotations, such as 'Fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF' and details the output structure. It also mentions the USPTO PatentsView API sunset in May 2025 and that it soft-fails. This adds meaningful context that annotations (readOnlyHint, idempotentHint) do not cover. 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 a single paragraph that front-loads example queries and key guidance. It is efficient but could be slightly improved with clearer structuring (e.g., bullet points for outputs). However, it contains no filler and earns its place.

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

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

Given the complexity of the tool (multi-source lookup) and absence of an output schema, the description provides a thorough list of returned fields (CIK, company name, filings with URIs, fundamentals, patents, news, LEI). It also notes the scope (US public companies) and a known limitation (patents soft-fail). This is sufficient for an agent to understand the tool's capabilities and limitations.

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 both parameters adequately. The description adds examples ('AAPL', '0000320193') and reiterates that names are not supported, but this does not significantly enhance semantic understanding beyond the schema. 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 states the tool's purpose: generating a full cross-source profile of a US public company in a single call. It provides example user queries and lists the specific data sources and outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from sibling tools like resolve_entity by explicitly noting when to use this tool instead.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies that names are not supported and advises using resolve_entity first if only a name is available. This clearly indicates when and how to use the tool vs alternatives.

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

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

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?

Adds extensive behavioral detail beyond annotations (readOnlyHint, etc.), including compatibility warnings, temporal alignment, and skipped counters. 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?

Somewhat verbose with multiple paragraphs and technical details. While front-loaded, the length could be trimmed without losing 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?

Compensates for missing output schema by describing response structure (prices, spreads, safety fields). Covers edge cases well. Minor lack of output schema is mitigated.

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?

Adds meaning beyond schema by explaining topic values and override behavior. Schema coverage is 100% with descriptions, and the description complements it with usage context.

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

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

The description clearly states it calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage. It specifies two modes (topic shortcuts and explicit pairings) with concrete examples.

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

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

Explicitly describes when to use topic shortcuts vs explicit tickers, and warns that most pre-mapped topics return compatibility warnings. Does not explicitly contrast with sibling tools, but the specificity makes appropriate usage clear.

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

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

Annotations already indicate 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 readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond that by disclosing the cross-source identity spine (SEC EDGAR, GLEIF, OpenFIGI), label provenance per identifier, explicit unresolved identifiers, graceful degradation when enrichment sources fail, and internal cascading lookups. This is rich, useful behavioral context.

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

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

The description is long but front-loaded with practical query examples and a crisp 'Use FIRST' directive. The SUPPORTED TYPES section is structured and dense, and the details about degradation and provenance are relevant. It is slightly verbose, but each section earns its place given the tool's complexity.

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

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

With no output schema, the description must communicate return behavior, and it does: identifiers labeled by source, unresolved identifiers explicitly stated, graceful degradation of LEI/FIGI enrichment, and the note about multiple internal lookups. It covers both supported types and input forms, though it stops short of specifying an exact JSON output structure.

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 has 100% coverage with clear descriptions for both parameters. The description adds meaning beyond the schema by explaining what each entity type resolves to (company: CIK+ticker+company_name+LEI+FIGI; drug: RxCUI+ingredient+brand) and by specifying accepted input forms (ticker, CIK, or name; brand or generic).

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 common query phrasings and then clearly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This identifies the specific verb, resource, and output, and distinguishes the tool from siblings by framing it as the identifier-resolution step before other tools.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use rule. It also notes that using it replaces 2-3 manual lookups, reinforcing its role. It does not explicitly name alternative tools or when-not-to-use cases, 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 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.