Ashby

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: scoring 0-100, dependency on API key for anthropic model, free default. 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?

Three sentences, front-loaded with the main action. Every sentence adds value: what it does, default model, optional key, return structure, and use cases. 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, but the description adequately explains the return format (per-model + combined view). All parameters are covered, use cases are given, and optional API key is explained. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, but the tool description adds valuable context beyond the schema: default model is Workers AI Llama-3.3-70b (free), underscore in `_apiKey` indicates it's passed through, and context parameter helps disambiguate common names.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It specifies the default model, optional Anthropic key via `_apiKey`, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is specific and distinguishes it from sibling tools.

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

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

The description mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the optional `_apiKey` and models parameter. No explicit 'when not to use' or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds detail on return contents (contact info, resume, interview history, status), complementing rather than 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?

The description is two sentences: the first succinctly states the purpose, the second lists return contents. No unnecessary words, front-loaded with key information.

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

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

Given the tool's low complexity, 2 required parameters, existing output schema, and annotations, the description sufficiently conveys purpose and return data. It omits error handling or auth details, but these are covered by the schema and annotations.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description explicitly states 'Get full candidate profile by ID' and lists specific return contents (contact info, resume, interview history, status). It clearly identifies the verb, resource, and scope.

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 when a specific candidate ID is known, but does not explicitly mention when to avoid this tool or provide alternatives (e.g., use ashby_list_candidates for listing).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating a safe, repeatable read operation. The description adds specifics on returned data (description, requirements, etc.), providing transparency beyond annotations.

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

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

The description is a single, concise sentence that front-loads the action ('Get full job posting by ID') and lists key return fields. It is efficient but could be slightly more detailed.

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 low complexity (2 params, no enums) and presence of an output schema, the description adequately covers the tool's purpose and return fields. It is sufficient for an agent to understand functionality.

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

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

Schema coverage is 100% with clear descriptions for jobId and _apiKey. The description does not add additional parameter information beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states the tool gets a full job posting by ID, listing specific return fields like description and applicant count. This distinguishes it from sibling tool 'ashby_list_jobs' which lists jobs without full details.

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

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

The description implies usage when you have a job ID, but it does not explicitly state when to use this tool over alternatives like 'ashby_list_jobs' or other tools. No exclusion criteria or context 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minimal extra transparency beyond listing returned fields. No mention of pagination behavior or authentication requirements beyond what schema provides.

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 concise sentence (15 words) that front-loads the action and outputs. No redundant information.

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

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

Given the tool has an output schema, the description need not fully document return values. It covers the main output fields. However, it could mention that results are paginated, but overall adequate.

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 each parameter is already documented. The tool description adds no additional meaning to parameters beyond what the schema provides. 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 function: 'Search job applications across positions' and specifies the returned fields (candidate name, applied job, application stage, submission date). This distinguishes it from sibling tools like ashby_list_candidates and ashby_list_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?

The description implies usage for searching all applications but does not provide explicit guidance on when to use this tool versus alternatives (e.g., ashby_list_candidates for candidates). No when-not-to-use advice.

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 and destructiveHint false, so the description's claim 'Search candidates' aligns. However, the description adds no additional behavioral context such as pagination behavior, rate limits, or permission requirements beyond what the schema provides.

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 efficient sentences with no wasted words. Information is front-loaded: purpose first, then output summary, then sibling reference. Very concise.

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

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

Given the output schema exists and annotations cover safety, the description is sufficient for a simple read-only search tool. It could improve by briefly noting pagination behavior, but it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% for all three parameters (cursor, _apiKey, per_page). The description does not add extra meaning beyond 'Search candidates' and mentions output fields but not parameter usage details. 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 uses a specific verb 'Search candidates' and identifies the resource 'your ATS'. It clearly distinguishes from the sibling ashby_get_candidate by noting that this tool returns names, emails, and application metadata, while the sibling provides full profile details.

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

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

The description advises to use ashby_get_candidate for full profile details, which implies this tool is for broad listing/searching. It does not explicitly state when not to use or provide alternatives, but the sibling differentiation is clear and helpful for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing safety. The description adds return details (job title, department, posting details) and filtering options, which 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?

Three short, focused sentences: main action first, then filtering, then return scope. No wasted words, easy to scan.

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

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

Given the simple tool (2 parameters, rich annotations, output schema present), the description fully covers necessary context. Return fields are succinctly stated; 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 coverage is 100% with parameter descriptions already present. Description reinforces status values but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Search open positions' with a specific verb and resource, and mentions filtering by status. It effectively distinguishes from sibling tools like 'ashby_get_job' (single job) and 'ashby_list_candidates' (different entity).

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 listing jobs with optional status filtering but lacks explicit guidance on when to use versus alternatives like 'ashby_get_job'. No direct when-not-to-use or prerequisite information.

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?

On top of the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses real behavior: it dispatches to other internal tools, fills their arguments, and returns structured answers with citation URIs. The legal/medical disclaimer is useful extra context; only minor gaps remain (latency, rate limits, failure modes), which the annotations do not cover either. No contradiction with the annotations.

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

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

The description is long (roughly 200 words) but intentionally structured: priority directive first, domain list and trigger phrases next, concrete examples, then sibling guidance and disclaimers. It earns most of its length, though a tighter pass could remove some redundancy among the examples and the legal/medical caveats.

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 router tool with no output schema, the description covers the calling context well: what inputs look like, what answers look like (citations), when to prefer it, and which siblings apply in corner cases. It does not spill edge cases like unsupported questions or failure modes, but nothing essential is missing for a correct call.

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 gives 100% coverage: it documents the question parameter and all five aliases (text, q, input, query, prompt). The description adds example questions but no structural semantics about the parameter itself, so it sits at the baseline rather than adding real parametric nuance.

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 gives a clear verb and resource: it routes a natural-language question to the right one of 5,596 tools across 1,465 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. Domain lists and sample questions ('current US unemployment rate', 'Apple's latest 10-K') sharpen the purpose, and sibling routing to deep_research and ask_pipe_worx_grounded keeps it distinct from adjacent 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 explicitly says 'PREFER OVER WEB SEARCH', then spells out trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and example prompts. It also tells the agent when NOT to use it: broad or multi-part fan-out questions should go to deep_research, and hallucination-resistant single answers with verbatim evidence should go to ask_pipeworx_grounded.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description's bar is lower. It adds valuable context beyond them: that routing results are non-deterministic over time because 'candidate routing improvements enabled live whenever one is under test,' that 'no candidate is active right now' so behavior currently matches ask_pipeworx, and that outputs are fed into a merge decision. This is behavioral insight the structured fields cannot express.

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 core identity is front-loaded in the first sentence; the rest earns its place with current state, usage direction, and a misconception fix ('Falls back to nothing — this IS a full working router'). There is slight redundancy between 'identical to ask_pipeworx' and 'matches ask_pipeworx exactly,' so it is not maximally tight, but no sentence is wasted.

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

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

For a parametric router tool with only one required parameter, an output schema, and thorough annotations, the description supplies what was probably missing: experimental status, the live deployment state, comparison purpose, and a fallback clarification. The only gap is that the exact response shape is delegated to ask_pipeworx rather than restated, which is reasonable given the sibling relationship.

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 carries the parameter documentation with descriptions clarifying that q/text/input/query/prompt are aliases for the one required 'question' parameter. The description's 'same arguments as ask_pipeworx' statement adds only marginal cross-tool confirmation, which is enough to hold the baseline of 3 but not exceed it.

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

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

The description states a specific function ('identical universal router, same 5,596 tools') and immediately frames it as the beta counterpart of ask_pipeworx, which distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded siblings. It tells an agent exactly what the tool is without opening the schema.

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

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

Gives an explicit selection condition — 'Use this exactly like ask_pipeworx when you want the newest routing' — and contrasts against the stable router being compared, so the agent knows what it signs up for. It does not explicitly state a 'when not to use' case (e.g., prefer stable ask_pipeworx when behavior must be pinned), so it stops just short of full exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description exposes the full failure contract: answer null plus one of five refusal_reason values. It also discloses the output shape, evidence as verbatim quote, and the extra LLM call cost, which are important invocation behaviors.

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

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

The description is dense but every sentence earns its place: behavior, return contract, failure enum, usage trigger, examples, and alternative. It front-loads the core distinction and keeps the guidance scannable.

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

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

Even though there is no output schema, the description provides a complete call contract: success shape, explicit refusal shape, refusal enum, and the distinction from ask_pipeworx. There is enough context for an agent to know when to invoke it and what to expect back.

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

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

Schema coverage is 100%, and all parameters are natural-language aliases of the same question value. The description does not add parameter-level meaning beyond the schema, but none is needed for correct invocation.

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

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

The description names a concrete behavior: a hallucination-resistant answer mode for high-stakes reads that extracts answers using only the tool result. It also distinguishes itself from the sibling ask_pipeworx by stating 'Same routing as ask_pipeworx' and adding grounded extraction and explicit refusals.

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

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

It explicitly says when to use the tool: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. It gives concrete example domains and states the alternative clearly: prefer ask_pipeworx for casual lookups, with a cost tradeoff.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral context: resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits on low confidence, closed market handling, wide-spread warnings, and cancellation rule parsing. 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 verbose with multiple paragraphs and technical detail. While all content is relevant, it could be more concise. Front-loading is good (first sentence states purpose). Structure uses section labels, but overall length may reduce quick readability.

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

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

Given the tool's complexity (multiple classifiers, fan-out packs, edge cases), the description covers all necessary aspects: input resolution, evidence sources, response shapes, resolver contract, parent events, news fields, safety mechanisms, and resolution rules. No output schema exists, but response shapes are described.

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%, yet the description adds significant meaning: explains 'depth' quick vs thorough, 'market' parameter with three accepted formats and examples, and 'include_raw' with size implications and use cases. 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 starts with a clear action verb ('Research') and specific resource ('Polymarket bet'), states inputs (slug, URL, question text), and output (evidence packet + comparison). It distinguishes from siblings by specializing in Polymarket betting research.

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

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

Explicitly suggests use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes classifier examples and fan-out scenarios. Does not explicitly state when not to use or point to alternative tools, but context is sufficient.

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 openWorldHint. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS, FDA), correct handling of off-calendar fiscal years for companies, and that results are sorted by primary metric. 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?

Description is dense but efficient: front-loads trigger phrases, then explains behavior per entity type, then output format. Every sentence serves a purpose with no redundancy. Well-structured for quick parsing.

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 mentions return of paired data with citation URIs, which is adequate. Covers key behaviors like data sources, sorting, and entity limits. Minor gap: does not specify response format (e.g., table or JSON), but overall complete for a comparison tool with rich annotations.

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

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

Schema coverage is 100% with descriptive parameter comments. Description adds practical usage details: examples of tickers vs CIKs for companies and drug names, plus reinforces the 2–5 range. This adds moderate value beyond the schema.

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

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

Description provides explicit trigger phrases and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs). It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison in one call.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies efficiency ('replaces 8–15 sequential lookups'). Provides clear when-to-use guidance with no ambiguity.

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 annotations only mark the tool read-only/idempotent; the description adds extensive behavioral context: auth and plan constraints, latency expectations, citations, explicit gap reporting rather than inventing facts, contradiction scanning, and semantic excerpting of long records. It communicates exactly what the agent should expect from the call.

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 carries unique value: auth routing, core behavior, return packet contents, usage boundaries, and behavioral caveats. It is front-loaded with the most important operational constraint (auth/plan) before diving into details. No filler or repetition.

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

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

Given that there is no output schema, the description compensates richly by enumerating the finding-packet fields, citation behavior, gaps[], contradictions[], and latency ranges. It also addresses question types and feature tiers, leaving an agent with a concrete mental model of the invocation and result. Very complete for a research tool of this complexity.

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

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

Schema coverage is 100%, with depth and question already described in the schema, so the baseline of 3 applies. The description mainly restates the depth semantics already present, though it adds a small amount of context by noting the paid requirement and the practical consequences for standard/thorough. It does not add substantial new parameter meaning.

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 a specific verb and resource: multi-source research across 1465 structured data sources, with decomposition into facets and parallel routing to tools. It explicitly contrasts itself with open-web search and positions itself relative to ask_pipeworx for single lookups. This meaningfully differentiates it from sibling tools.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, while single lookups should use ask_pipeworx. It also provides a concrete conditional rule: if not signed in, use ask_pipeworx. This is unambiguous and names the alternative.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full schemas and examples, ready to call directly.

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

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

Front-loaded with purpose, then lists domains and return format. Slightly long but clear 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?

Comprehensive for a discovery tool with 6 params (1 required). Explains return format sufficiently without output schema.

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

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

Schema coverage is 100% and description reinforces the query parameter's purpose with examples, though it doesn't add much beyond the schema.

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

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

The description clearly states it finds tools by describing data/task, listing many domains. It distinguishes from siblings as a meta-tool for discovery.

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

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

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

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and mentions the USPTO PatentsView API sunset and soft-fail. 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 front-loaded with examples and the core purpose. It includes useful return field details but is slightly verbose. Every sentence adds value, though it could be trimmed slightly for 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?

Despite no output schema, the description enumerates return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their structure. It covers data sources and constraints (e.g., recent_filings up to 5). For a complex tool, this is fairly complete.

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

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

Schema description coverage is 100%, and parameters have clear descriptions. The description reinforces that value is either ticker or CIK and that names are unsupported. It adds no new semantic detail beyond the schema, 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 starts with multiple user intent examples (e.g., 'Tell me about X', 'brief me on Tesla'), then explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb (profile/research) and resource (company). Sibling tools like search_within or resolve_entity are distinct, so this tool is well-differentiated.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also warns that names are not supported and advises using resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; description adds context about clearing sensitive data but no further behavioral details.

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

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

Two concise sentences, front-loaded with key action, no 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?

Single-parameter tool with clear purpose and usage guidelines; sibling references complete the context.

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

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

Schema provides full coverage (100%) with description 'Memory key to delete'; tool description does not add additional semantic details 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?

Clearly states 'Delete a previously stored memory by key.' with specific verb and resource, and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data...' and suggests pairing with remember/recall.

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 process details: fetches page, extracts title/description/links, outputs a single text blob. 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 well-structured sentences, no unnecessary words. First sentence states purpose, second explains process, third lists use cases. Highly 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 two parameters, no output schema, and comprehensive annotations, the description provides adequate context: output format, target audience, and use cases. Missing potential error scenarios (e.g., invalid URL) but acceptable for a simple read-only 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 does not add significant new meaning beyond the schema—it only mentions 'extracts title/description/key links' without detailing parameters.

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

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

Clearly states the tool generates an llms.txt file for AI crawler indexing, with a specific verb and resource. It distinguishes itself from sibling tools like scan_competitor_ai_presence by its unique purpose.

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

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

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing). Does not mention when not to use or alternatives, but the use cases are clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return fields and context about include_inactive, providing value beyond annotations.

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

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

Two concise sentences: first states purpose, second gives usage guidance. No fluff, 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?

Simple tool with one optional parameter, no output schema, and clear annotations. Description covers return fields, usage context, and parameter implication sufficiently.

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

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

Schema coverage is 100% with description for include_inactive. The description does not add new parameter details but implies the parameter by mentioning 'active'. Baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' – specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly tells when to use it, though does not mention when not to use it.

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

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

Annotations are all false and provide no safety profile, so the description carries the full burden. It discloses the claim_token workflow, that the team reads digests daily, rate limits (5 per identifier per day), and that it is free and does not count against quota. This is rich behavioral context well beyond the annotations.

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

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

Although the description is long, every sentence earns its place: purpose, usage scenarios, exclusions, formatting advice, claim_token flow, rate limit, and quota. It is front-loaded with the core action and clearly structured, making the length 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?

Despite the lack of an output schema, the description explains the key return behavior (claim_token) and how to follow up on a previous report. It also covers context like rate limiting and daily processing. For a feedback tool with optional parameters, this is complete and actionable.

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 value by mapping type enum values to real-world scenarios, advising on message content (don't paste end-user prompts), and demonstrating usage of claim_token. However, it doesn't elaborate on the context object beyond the schema, so not a full 5.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately clarifies the tool's scope and later distinguishes it from other MCP servers' feedback mechanisms, making it clearly different from sibling tools.

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

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

Explicit 'Use when' conditions cover bug, feature/data_gap, and praise scenarios. It also gives a clear 'when not to use' by excluding tools from other MCP servers and directs users to file with that server instead. Advice on how to describe issues and use claim_token further strengthens 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 valuable context: self-aggregating signal, no PII, and caching behavior (5min-1h). No contradictions.

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

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

The description is concise (3 sentences), uses bullet points for use cases, and front-loads the core purpose. Every sentence adds value without redundancy.

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

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

The tool is simple (one optional param, no output schema). The description explains the return structure, caching, privacy, and window semantics. It is fully adequate for an agent to understand usage and expectations.

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

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

Schema coverage is 100% with enum description. The description adds meaning by explaining the trade-off: shorter windows for hot trends, longer for steady-state demand. This helps the agent choose the right window.

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 returns top tools, top packs, and total call volume over selected windows. The verb 'returns' and the specific resources ('top tools, top packs, total call volume') make the purpose unambiguous. It distinguishes itself from sibling tools like discover_tools by focusing on trending social proof.

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 three explicit use cases (discovering hot sources, confirming popular tools, checking alignment) and explains window choices (short vs. longer windows). It lacks explicit when-not-to-use guidance, but the context is clear enough for an AI 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?

The description provides rich behavioral context beyond annotations: monotonicity checks, partition sum logic, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against CLOB depth, and warnings like 'do not trade it' when realizable_edge_pp ≤ 0. No contradictions with annotations.

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

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

The description is fairly long but every sentence adds value. It is front-loaded with the core purpose and mode distinctions. Minor improvement could be breaking into sections, but it remains clear and not verbose.

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

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

Despite no output schema, the description explains the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, etc., and partition_check fields. It also covers edge cases like fill check and custom sizing. 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 coverage is 100% for both parameters. The description adds deep semantic meaning: explains what event string format is accepted (slug or full URL), what topic represents (seed question), and how each mode uses the parameter. This goes beyond the schema's short 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 explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (no args for trending scan, event for single-event, topic for cross-event) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives clear guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for per-event partition_check, or `topic` for cross-event scan.' It recommends 'event (recommended for a specific market)' and explains what each mode does. It lacks explicit 'when not to use' but is still very 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?

The description goes far beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It details caching (1h at KV level), diagnostics output, the three model families, and how Fed bets are handled. No contradictions with annotations.

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

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

The description is relatively long but well-organized into sections. It is front-loaded with the core purpose. Every sentence adds information, though some detail (e.g., exact α values) could be moved to documentation. Still, it is efficient for the complexity.

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

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

Given the complexity (9 parameters, 3 segments, multiple model families, caching, diagnostics, and no output schema), the description is exceptionally complete. It explains response structure (by_segment, fed_candidates, diagnostics) and how to handle empty segments, leaving no major 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?

All 9 parameters are described in the schema (100% coverage), and the description adds significant value beyond the schema. For example, it explains slippage_pp context (Polymarket fees, bid/ask), max_spread_pp and min_liquidity as 'tradeable-edge filters', and min_partition_leg_kelly clarifies why min_kelly doesn't filter partitions.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb and resource. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge discovery and explicitly mentioning the purpose 'Built for "what should I bet on today"'.

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

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

The description gives clear context for when to use the tool ('what should I bet on today') and explains tuning knobs like min_liquidity and max_spread_pp. However, it does not explicitly exclude cases when alternatives should be used (e.g., polymarket_arbitrage for pure arbitrage).

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 significantly expands on annotations (readOnlyHint, idempotentHint) by detailing data sources (daily snapshots), limitations (60-day TTL, snapshot gaps), computation details (decay from daily closes), and response structure. No contradictions with annotations.

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

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

The description is information-dense and front-loaded with the core purpose. Every sentence adds value, but it is somewhat lengthy. A slightly more concise rewrite could improve readability without losing content.

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

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

Given 2 parameters with 100% schema coverage and no output schema, the description thoroughly explains the response fields (tracked[], expired[], snapshot_dates[]), includes limitations, and covers edge cases (gaps, TTL). It is fully complete for an agent to 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?

Both parameters have schema descriptions, but the description adds meaningful context: default values (days=14, window='1wk'), clamping (2-30 for days), and explains the 'window' as a snapshot family. It also provides the response structure, which is valuable 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 provides 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and decay metrics.

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

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

The description gives clear context on when to use (e.g., assessing if an edge is fresh or old) and the rationale behind it. However, it does not explicitly state when not to use or provide alternatives like polymarket_edges for current edges.

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, and non-destructive behavior. The description adds substantial behavioral details: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket mode includes per-leg fill detail, thin_legs, forced_directional_risk. This goes far beyond the annotations in explaining behavior.

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-structured, front-loading the core function and then clearly separating single-market and basket modes with headings. Every sentence serves a purpose, explaining mode-specific arguments, return values, and usage rationale. It is concise given the complexity of the tool.

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

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

Given the tool's complexity with two modes and multiple return fields, the description covers all necessary aspects: mode-specific parameters, return values for each mode, edge cases (thin legs, partial fills), and actionable guidance. No output schema is provided, but the description fully compensates by enumerating all return fields.

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

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

Input schema already describes all 4 parameters with 100% coverage, which sets a baseline of 3. The description adds value by contextualizing parameters within single-market vs basket modes, explaining the default for side in basket mode, and clarifying size_usd semantics for each mode (spend vs target proceeds vs settlement notional). This enriches understanding beyond the schema's descriptions.

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

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

Description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This specific verb+resource distinguishes it from sibling tools like polymarket_arbitrage (signal generator) and polymarket_edges (edge detection), which are about generating signals rather than verifying fill feasibility.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by extensive details: the tool explains safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and conditions where spreads are meaningless. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose, then modes, response, and safety fields. While every sentence adds value, it is somewhat long and could be slightly more concise.

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

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

With 3 parameters and no output schema, the description thoroughly covers the tool's behavior, input modes, response structure, edge cases (compatibility warnings, temporal alignment), and provides specific examples. No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the two modes (topic vs. explicit) and that kalshi_event_ticker/polymarket_event_slug override mapped values, going beyond the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing itself from sibling tools like polymarket_arbitrage which focus on single-venue opportunities. The two modes (topic and explicit) are clearly defined.

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 find spreads), when not (when compatibility_warning fires due to non-equivalent bet shapes or unrelated events), and that pre-mapped topics often return warnings. It could mention alternative tools more explicitly but provides sufficient 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 indicate readOnly, idempotent, non-destructive. Description adds scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' 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, no wasted words. Front-loaded with purpose, then usage and scoping. Excellent structure.

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?

Single optional parameter, no output schema, annotations present. Description fully covers usage, scoping, and pairing with siblings. 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%. Description explains optional key parameter: 'omit the key argument to list all keys', adding 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?

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This specifies the exact action and resource, and distinguishes from sibling tools (remember, forget).

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

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

Describes use case: 'look up context the agent stored earlier' and pairs with remember/forget. No explicit when-not or alternatives, but context is clear.

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

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

Annotations already declare readOnly and idempotent. Description adds that mark_read:true advances the cursor for subsequent calls, and explains return payload fields (source, citation_uri). This is valuable 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?

5 sentences, no redundancy. Front-loaded with purpose, then explains parameters and usage. 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?

No output schema, but description explains return fields. Covers filtering, mark_read, polling, and alternative endpoint. Complete for a read-only alert retrieval 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 has 100% coverage, but description adds example for type ('sec_8k') and clarifies mark_read behavior ('flag returned events read so the next call only shows newer ones'). This adds 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?

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It differentiates from sibling tools like list_subscriptions by focusing on fired events/alerts.

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 filtering options (type, since) and mentions polling suitability. Includes alternative access via URL for scripts/dashboards. Could explicitly state when not to use, but context is strong enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fan-out behavior, fallback mechanism from GDELT to GNews on rate limits/5xx, USPTO soft-failure due to PatentsView API sunset, and the returned structure (changes grouped by source, total_changes count, pipeworx:// URIs). No contradiction.

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

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

The description is a single dense paragraph that efficiently conveys all needed information. It is front-loaded with example queries. Could be slightly more structured (e.g., bullet points for sources) but remains concise and informative.

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

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

Despite no output schema, the description adequately explains the return format and all key behavioral aspects: multi-source fan-out, fallback logic, known limitations (USPTO soft-fail), and parameter usage. Covers all essential context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: relative shorthand for 'since' (e.g., '7d', '1y'), explicit recommendation of '30d' or '1m' for monitoring, and examples of valid 'value' inputs (ticker or CIK). This exceeds the baseline.

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

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

The description clearly states the tool's purpose as a change feed for a company within a time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes itself from the sibling tool 'entity_profile' by contrasting dynamic vs static profiles.

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 guidance, including example queries ('What's new with X', 'latest on Y'), when to use this tool vs 'entity_profile', and details on the 'since' parameter format with recommended defaults ('30d' or '1m').

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

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

Description adds value beyond annotations: scoped by identifier, persistence details, and idempotent nature. No contradiction with annotations (readOnlyHint false, idempotentHint true).

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

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

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

Given no output schema, description covers behavior, persistence, pairing, and usage scenarios. Complete for a simple key-value store tool.

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

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

Schema coverage is 100% with adequate descriptions. Description enhances with practical examples of keys (e.g., 'subject_property', 'target_ticker'), adding meaning beyond schema. Baseline 3, plus 1 for extra context.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, using a specific verb-resource pair. It distinguishes from siblings like recall (retrieve) and forget (delete).

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. It describes pairing with recall and forget, and provides context on scoping and persistence (auth vs anonymous).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds significant behavioral context: the tool cascades through multiple lookup endpoints, degrades gracefully when external sources are unavailable, returns identifiers with source labels, and explicitly lists unresolved identifiers. It does not contradict any annotation.

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

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

The description is long but well-structured: it leads with example queries and a clear usage directive ('Use FIRST'), then details supported types with relevant technical information. Every sentence contributes necessary context given the tool's complexity (multiple data sources, fallback behavior). It could be slightly more concise, but the length is justified.

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 thoroughly explains what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI) and how they are resolved. It covers graceful degradation, unresolved identifier handling, and the range of accepted inputs. Given the tool's complexity (2 parameters, cascading lookups, multiple entity types), the description is fully complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the 'value' parameter accepts ticker, CIK, ISIN, or company name for company type (with ISIN resolving to legal entity via GLEIF), and brand or generic name for drug type. It also clarifies that multiple input formats are acceptable, which is not fully covered in the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: resolve user-spoken names to official identifiers. It provides multiple example queries, explains supported entity types (company and drug), and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like entity_profile or compare_entities that likely require already-resolved IDs.

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

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

The description explicitly advises using this tool first when a name needs an ID, establishing a clear usage context. It details supported input types (ticker, CIK, ISIN, name for company; brand/generic name for drug) and explains fallback behavior. However, it does not explicitly state when not to use it or provide alternatives, though the 'Use FIRST' guidance implies scenarios where it is most appropriate.

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

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

Discloses internal use of ai_visibility_check, ranking by score, and output format (ranked list with score, confidence, signal density). Annotations already declare readOnlyHint, openWorldHint, idempotentHint; description adds meaningful behavioral 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?

Two concise sentences: first states action, second adds context and output details. No superfluous words, 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?

Describes output (ranked list with score, confidence, signal density) in absence of output schema. Covers required parameter (entities) and optional details. Complete for a comparison tool.

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

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

Schema coverage is 100%, and description does not add substantial meaning beyond parameter descriptions. Mentions default model and array size, but these are covered in schema.

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

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

Description uses specific verb 'Compare AI visibility' and resource 'multiple entities', clearly distinguishes from sibling ai_visibility_check which checks a single entity. Provides example use case to clarify purpose.

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

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

States usefulness for competitive AI-marketing audits with concrete example. Implicitly suggests when to use (multiple entities) vs ai_visibility_check (single entity) but does not explicitly exclude alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral details such as fan-out to two services, potential 5-30s timeout for new versions, and return of a summary block with specific fields. This exceeds what annotations alone provide.

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

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

The description is well-structured with the core purpose upfront ('Composite check in ONE call'), followed by details on return value, ecosystem limitations, and error behavior. Every sentence adds value, and the length is 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?

Since no output schema is provided, the description fully enumerates the return fields (summary block fields, advisory details, links, alternative versions) and explains partial failure behavior. No critical information is missing for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds implicit context by explaining how parameters are used (e.g., 'Defaults to the latest published version when omitted') and constrains the 'package' parameter to the npm ecosystem. This provides meaningful 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 clearly states the tool's purpose: a composite check for npm packages that gathers license, advisories, version history, and bundle size info. It differentiates itself from sibling tools like 'deep_research' and 'scan_competitor_ai_presence' by focusing on a specific npm package evaluation.

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 specifies when to use this tool (e.g., 'is X safe / popular / small') and provides alternatives for other ecosystems (PyPI, Maven, etc.). It also mentions graceful degradation for partial failures, giving clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, caps input at 200K chars with truncation and flagging. 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 appropriately sized and front-loaded with the core purpose. Every sentence provides useful information without redundancy. Could be slightly more concise, but overall well-structured.

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

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

Given the complexity and no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores), truncation behavior, and technical specifics (embedding model, window size). Sufficient for an 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 coverage is 100% with all three parameters described. The description adds meaning beyond the schema by explaining the nature of 'query' with examples, specifying that 'text' is the document to search inside with a max length, and clarifying 'limit' as max passages with a default and range.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples like SEC 10-K body or article. It distinguishes from siblings by noting it is for searching within a specific text, and pairs 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 says to use when the record is too big for the prompt, saving context and returning only relevant passages. It also provides pairing guidance with ask_pipeworx_grounded and outlines when to avoid using 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?

Annotations declare idempotentHint=true, but description adds that it creates a new subscription. It also discloses important behavior: phone must be verified before sms delivery, 10/day sms cap, webhook auto-disabled after 10 consecutive failures, and the one-time nature of webhook secret. 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 front-loaded with the purpose and returns value. It is moderately long but each sentence adds valuable information. Could be slightly improved with bullet points for readability, but overall it is well-structured and not redundant.

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 description mentions the return value (new subscription id). It covers all parameters and their constraints, explains delivery channels in depth, and addresses preconditions (phone verification, account type). For a complex tool with nested parameters, the description is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning beyond the schema: it explains the enum values for 'type' with concrete examples (e.g., 'sec_8k: items:["5.02"] = officer change'), details the 'params' object structure for each type, and clarifies constraints on 'delivery' fields (e.g., sms must match verified phone, webhook secret only returned once).

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

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

Description clearly states it 'creates a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id'. This is a specific verb+resource, and it distinguishes from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts'.

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 this tool (to set up monitoring) and includes alternative delivery methods: 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json' for the feed. It also mentions that anonymous users cannot persist subscriptions, requiring a Pipeworx OAuth account. However, it does not explicitly state when not to use this tool.

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

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

Adds context beyond annotations: explains output format (category buckets with exact tool+argument shape), behavior with no args vs topic, and connection to live catalog. No contradictions with annotations.

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

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

Description is thorough but slightly verbose. Well-structured with common queries, output description, usage, and when-to-use. Every sentence is valuable but could be tightened.

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 and single optional parameter, the description fully covers functionality, usage, and outcomes. Comprehensive for an onboarding tool.

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

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

Schema coverage is 100% and description adds example values ('finance', 'pharma', etc.) and clarifies omission behavior, significantly enriching the parameter meaning.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool calls, and distinguishes it from meta-tools like ask_pipeworx. Uses specific verbs and resource identification.

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 this FIRST' and describes how to call with/without topic. Lacks explicit exclusions but provides clear context for appropriate use.

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

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

Adds context beyond annotations: ownership enforcement, deactivation instead of deletion, and impact on historical events. Annotations already indicate idempotent and non-destructive; description aligns and enriches.

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

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

Two sentences, front-loaded with the core action, each sentence adds essential 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?

Covers purpose, side effects, ownership, and relation to other tools ('recent_alerts'). Although there is no output schema, the tool is simple; the description is sufficient for correct 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 has 100% coverage with a clear description of the 'id' parameter. The tool description does not add further parameter details, but it provides ownership context that relates to the parameter. Baseline of 3 is appropriate.

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

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

Clearly states the action 'cancel a subscription' by id, distinguishing from siblings like 'subscribe' and 'list_subscriptions'. Mentions that it deactivates rather than deletes, which is a key behavioral detail.

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 ownership enforcement ('you can only cancel your own subscriptions'). Implies when to use, but does not provide explicit alternatives or exclusions. The reference to 'recent_alerts' indirectly guides post-cancelation behavior.

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/not destructive, but the description goes far beyond by clearly explaining the compound nature (replaces 4–6 sequential calls), the specific verdict values, the critical distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found), and the presence of verification_error details. This is valuable behavioral context beyond the structured 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 longer than average but every part earns its place: example phrasings, purpose, routing logic, return values, and caller warnings. It is well-structured and front-loaded with examples, though slightly wordy in the middle. It is appropriately sized 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?

The tool is complex (two execution paths, multiple verdict types) and has no output schema, so the description must explain return values and edge cases. It does so thoroughly, including the meaning of each verdict, the citation format, and special handling for failures. This is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

With 100% schema description coverage, the baseline is 3, but the description substantially enriches both parameters: it gives concrete examples for 'claim' and explains the behavior of 'tolerance_pct' (default implied by wording, capped at 5, overrides, and use cases for hallucination detection). This adds meaningful guidance beyond the schema.

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

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

The description states a specific verb ('verify') and resource ('natural-language factual claims against authoritative sources'), includes concrete example phrasings, and clearly distinguishes this tool from sibling research/comparison tools. It is unambiguous about what the tool does and returns a verdict.

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

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

The description explicitly says to use it whenever the agent needs to check whether something a user said is factually correct. It also explains the two distinct routing paths (company-financial vs. other claims) but does not explicitly mention when NOT to use the tool or name alternative tools for non-verification tasks.

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