Devdocs Io

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

Annotations already declare readOnlyHint, non-destructive. Description adds: per-model return format, free vs paid model, API key pass-through. Does not contradict 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?

Concise with front-loaded main action, every sentence adds value. 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?

Complete for a query tool with good annotations and schema. No output schema but description explains return shape 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?

100% schema coverage. Description adds meaning: default model behavior, API key condition, context disambiguation, and return structure (score, confidence, signals, raw_response, combined view).

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

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

Description clearly states the tool probes LLMs for brand/product visibility and scores it (0-100) per model. Distinguishes from siblings like scan_competitor_ai_presence by focusing on direct LLM query and scoring.

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

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

Provides clear usage context: default free model, Anthropic requires own key/payment, and use cases (AI marketing audits, brand checks, competitive monitoring). Lacks explicit when-not-to-use or 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 provide readOnlyHint, openWorldHint, idempotentHint as true, which the description complements by detailing routing behavior, citation URIs, and performance characteristics ('one fast call', 'works on every tier'). No contradictions.

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

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

The description is front-loaded with key guidance and examples, but is somewhat long. It could be tightened without losing value, but every sentence is 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?

For a complex tool accessing 4,484 sources, the description fully covers what the tool does, when to use it, how it works, and what it returns. No output schema is needed as the description clarifies structured answers with citations.

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

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

Schema coverage is 100% with a clear description for the 'question' parameter and its aliases. The description does not add new semantics beyond examples, which are helpful but not essential. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose with specific verb phrases: 'PREFER OVER WEB SEARCH for questions about...' and enumerates numerous data types. It distinguishes itself from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and giving usage guidance.

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

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

Provides explicit when-to-use advice ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-not-to-use (step up to grounded or deep research), and gives concrete examples. This is exemplary guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses internal process ('same routing as ask_pipeworx... then extracts the answer using ONLY what the tool result contains'), success/refusal response structure, and extra LLM cost. No contradiction with annotations.

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

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

Concise with three well-structured sentences: purpose, process, usage guidance. No wasted words, front-loaded with key information.

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

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

Despite no output schema, the description details the exact return structure on success and failure, making the tool's behavior fully understandable for high-stakes use. All relevant aspects are covered.

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

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

Schema description coverage is 100% (all 6 parameters described). The description does not add new semantic meaning beyond confirming aliases are for the question, meeting the baseline of 3.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, distinguishing it from sibling ask_pipeworx. The verb is implied in 'extracts the answer' and the resource is the grounded answer mode.

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

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

Explicitly provides when-to-use ('Use whenever an answer will be quoted, cited, or acted on') and when-not-to ('prefer ask_pipeworx for casual lookups'), including cost trade-off ('Costs one extra LLM call').

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 true, destructiveHint false. The description adds extensive behavioral context: resolution contract (confidence, alternatives, suggestions), parent event extraction, news fallback fields, safety behaviors (low confidence short-circuits, closed markets skip fan-out), liquidity 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 very long and dense, packing extensive detail but lacking structural sections. It is front-loaded with the main purpose, but the length may overwhelm agents. Every sentence is informative, but conciseness could be improved.

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 (classifiers, fan-out sources, response shapes, edge cases), the description is remarkably complete. It covers safety, cancellation rules, parent events, news fallbacks, liquidity warnings, and response structure. With no output schema, it effectively describes the return shape.

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

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

Schema coverage is 100% (all 3 parameters described). The description goes beyond by explaining depth (quick vs thorough), include_raw (default false, with summary vs full payload), and market input formats (slug, URL, question text). It adds semantics not captured in schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, or question text) and outputs (evidence packet + comparison). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on data research and fan-out.

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

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

The description provides explicit guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives concrete examples of fan-out per bet type (e.g., BTC bet → coingecko + fred + gdelt+gnews). It warns about low-confidence resolutions and closed markets, and advises inspecting market_match_confidence before trusting analysis.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description reveals detailed behavior: for companies, it pulls latest 10-K data with specific financials and handles off-calendar fiscal years; for drugs, it fetches FAERS counts, FDA approvals, and active trials. It also notes sorting by primary metric and returns paired data with citation URIs, providing comprehensive transparency.

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

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

The description is a single, well-structured paragraph that front-loads common query phrases and key directives. Every sentence adds necessary information: usage triggers, entity types, data sources, result sorting, and efficiency claim. No repetition or filler, making it highly concise and effective.

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

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

Given the tool's complexity (multiple entity types, parallel call, sorting, citations), the description covers all essential aspects: supported entities, data pulled, sort order, output format (paired data + URIs), and efficiency advantage. No gaps remain despite the absence of an 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?

The input schema already covers both parameters with descriptions and constraints (type enum, values min/max items). The description adds value by providing concrete format examples (tickers like AAPL, drug names like ozempic) and clarifying the data source per type, enhancing the schema's information.

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

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

The description clearly specifies the tool's function: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides concrete example queries ('Compare X and Y', 'X vs Y', etc.) and distinguishes it from sequential single-entity lookups, leaving no ambiguity about its 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?

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides context for entity types (company: tickers/CIKs, drug: names). It covers usage scenarios like ranking, head-to-head, and 'which is bigger,' making alternatives clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds minor context ('for a doc (large)') but does not disclose any additional behavioral traits beyond the annotations.

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

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

The description is extremely concise (one sentence), but it sacrifices informativeness. It is not front-loaded with useful 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 simplicity (one parameter, no schema descriptions, rich annotations), the description is completely inadequate. It fails to clarify the tool's purpose, return value, or how to use it.

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

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

The input schema has 0% description coverage, and the tool description does not explain the meaning or usage of the required 'slug' parameter. No value is added over 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 'Content database for a doc (large)' is vague and does not specify what action the tool performs. It merely describes what it is, not what it does, and does not distinguish it from sibling tools like 'docs' or 'search_docs'.

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?

No guidance is provided on when to use this tool versus alternatives. The description lacks any context for appropriate usage scenarios.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses key behavioral traits: parallelism (decomposes into facets, routes to 4500 tools in parallel), output structure (findings packet with verbatim evidence, confidence, source, fetched_at, citation, and gaps[]), expected latency (15-60s), and dependency on structured data (not open-web). No contradictions with annotations.

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

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

The description is long but well-structured. It front-loads critical info (account requirement), then states purpose, then alternatives, then behavioral details, then performance. Every sentence adds value. Could be slightly more compact, but given the tool's complexity, 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?

Given the tool's complexity (multi-source parallel research, no output schema), the description is remarkably complete. It covers prerequisites (account), behavioral traits (parallelism, gaps), output structure (findings packet), limitations (not for news, not open-web), and performance expectations (15-60s). The context signals show high schema coverage, and the description compensates for the lack of output schema by describing the return format.

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

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

Schema coverage is 100% (both depth and question documented), so baseline is 3. The description adds value: it explains depth values with numeric facet counts (quick=3, standard=5, thorough=8) and notes the paid requirement for 'thorough'. It also clarifies that the question can be broad/multi-part. This enriches the schema meaning beyond enum labels.

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: "Grounded multi-source research across Pipeworx's 1137 structured data sources". It specifies the verb (research), resource (structured data sources), and scope (broad/multi-part questions). It distinguishes itself from sibling tools like ask_pipeworx by noting its suitability for complex, multi-faceted queries versus single lookups.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: "Best for broad/multi-part questions over structured data", "For a single lookup use ask_pipeworx", and "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx". It also gives an alternative if not signed in: "If you are not signed in, use ask_pipeworx instead". These clearly help the agent decide between 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 already indicate readOnly and idempotent. Description adds that results include full schemas with examples and are ready to call directly, no second lookup. 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?

Concise, well-structured, and front-loaded with the main action. Lists domains and return details efficiently. Could slightly reduce domain list length but is reasonable.

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

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

Covers main purpose, input parameters, and output format. No output schema, but description adequately explains what is returned. Missing error handling details but acceptable for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about the query parameter's purpose and lists aliases, but does not add new meaning 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?

Clear, specific verb ('find', 'discover') and resource ('tools'). Distinguishes itself from siblings as a meta-tool for discovering other tools, listing specific domains.

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

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

Explicitly states when to use: when you need to browse, search, or discover tools. Also recommends 'Call this FIRST' to see the option set. Does not explicitly mention when not to use, but context is clear.

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

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

Annotations already convey readOnly, openWorld, idempotent, non-destructive. Description adds specific data returned (catalog with fields) and source (DevDocs.io), but no additional behavioral traits beyond annotations.

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

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

Single sentence, front-loaded, no wasted words. Efficiently conveys purpose and output.

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

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

Given zero parameters and presence of output schema, description fully covers what the tool does and returns. 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?

No parameters; schema coverage 100% trivially. Description adds no param info but not needed. Baseline 4 for 0 params.

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

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

Description clearly specifies verb 'Return', resource 'full DevDocs.io catalog of all available documentation sets', and lists returned fields (name, slug, type, version, release). Distinguishes from siblings like search_docs which search within docs.

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?

No explicit when to use or alternatives. Context implies it's for getting full catalog, but lacks direct guidance compared to siblings like search_docs or db.

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 and idempotent. The description adds significant behavioral context: fans out across multiple sources, returns specific fields, notes USPTO API sunset (soft-fails), and explains input constraints. No contradiction with annotations.

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

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

The description is a dense paragraph but front-loaded with examples. It covers all necessary information without excessive verbosity; however, it could be slightly more 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?

Despite no output schema, the description details what the tool returns (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI). Given the tool's complexity, this is sufficiently complete for an agent to understand the output.

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 parameters are well-described. The description adds value by explaining that value can be ticker or zero-padded CIK, and reiterates that names are not supported. This goes beyond the schema's description.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company. The examples ('tell me about X', 'research Acme') make the purpose immediately clear, and it distinguishes from sibling tools like resolve_entity and compare_entities.

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

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

The description explicitly states when to prefer this tool over chaining single-pack lookups, and warns that names are not supported (use resolve_entity first). This provides excellent usage guidance and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond what annotations provide (e.g., no mention of caching, formatting, or limitations).

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?

Extremely short at 3 words, but fails to include essential information. Front-loaded but at the cost of clarity and completeness.

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 2 required parameters, no enums, and an output schema present, the description is woefully incomplete. It does not specify what the HTML represents, how parameters affect output, or any return value details.

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

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

Schema coverage is 0% (no descriptions for 'path' or 'slug'). Description does not explain parameter meanings or expected formats, leaving the agent without semantic guidance.

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

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

Description 'Single entry HTML.' is vague; does not specify what kind of entry or how it differs from sibling tools like 'docs' or 'entity_profile'. The title 'Entry' offers little additional context.

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?

No guidance on when to use this tool versus alternatives. Sibling tools include many content retrieval tools (docs, search_docs, entity_profile), but the description provides no differentiation.

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 destructive and idempotent. Description adds context about clearing sensitive data and usage scenarios 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 sentences, no filler, front-loaded with core action and purpose.

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

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

With one parameter, full schema coverage, and annotations covering behavior, description is complete for a delete operation.

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

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

Schema coverage is 100% and description adds little beyond what 'key' parameter description already provides. Baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key', identifying verb, resource, and parameter. Distinguishes from siblings '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?

Explicitly provides when to use: 'context is stale, task is done, or clear sensitive data'. Also mentions pairing with related tools.

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

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

The description adds behavioral context beyond annotations: it fetches the page, extracts title/description/links, and outputs a standard llms.txt markdown blob. This complements the `readOnlyHint` and `idempotentHint` annotations without contradiction.

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

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

The description is four sentences, front-loads the main action, and avoids redundancy. Each sentence adds useful detail without being 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?

Given no output schema, the description adequately explains the output as a single text blob in markdown format. Parameters are fully covered. The tool's simplicity means the description is sufficiently complete.

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

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

Schema coverage is 100%, so the description adds limited value beyond the schema. It restates the `url` parameter's purpose and mentions `max_links` default/max values, but these are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, specifying the verb 'generate' and the resource. It provides context about fetching the page and extracting metadata. However, it does not differentiate from siblings like `ai_visibility_check` or `scan_competitor_ai_presence`, which could overlap.

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 lists explicit use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor visibility. It does not explicitly state when not to use it or name alternatives, but the usage context is clear and practical.

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, and idempotentHint true, so the description adds minimal behavioral context. The phrase 'entries inside a doc' adds some scoping but lacks details on output format or limitations.

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?

Extremely concise (4 words) but at the expense of completeness. The structure is minimal, and the description does not provide enough information to justify its brevity.

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 output schema and annotations, the description fails to convey what the tool does comprehensively. It does not explain the nature of 'index' or how the output relates to the input slug.

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 0%, and the description does not explain the 'slug' parameter. Examples exist in schema but no textual guidance, leaving the agent to infer the parameter's purpose.

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 'Index of entries inside a doc.' is somewhat vague but distinguishes from siblings like 'entry' and 'search_index'. It indicates a listing or table of contents for a document's entries, but does not specify what an entry is or what doc refers to.

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?

No guidance on when to use this tool versus alternatives like 'search_index' or 'entry'. No exclusions 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by explaining the default behavior (active only) and listing return fields. However, it does not reveal any surprising behavioral traits beyond what annotations imply.

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

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

Two sentences, no wasted words. The first sentence lists purpose and return fields; the second provides usage guidance. Every sentence earns its place.

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

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

For a simple read tool with one optional parameter and no output schema, the description is fairly complete: it explains return fields, default behavior, and usage. It could mention pagination or limits, but not essential for basic usage.

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

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

Schema coverage is 100% with a description for 'include_inactive'. The description adds the context 'active by default' and links parameter to functionality, but does not add significant new meaning beyond the schema.

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

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

The description explicitly states the verb 'list', the resource 'subscriptions', and scope 'caller's active'. It also lists the return fields and provides usage context (review before adding or to find id to cancel), differentiating it from siblings like subscribe and unsubscribe.

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

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

The description explicitly tells when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. It implicitly indicates when not to use (for other actions), but does not explicitly name alternatives. Clear enough for a simple 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?

Annotations only indicate non-destructive, non-read-only behavior. The description adds valuable behavioral context: rate-limited to 5 per identifier per day, free, counts against quota, and feedback is reviewed daily. This goes beyond what annotations provide.

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

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

The description is two well-structured paragraphs: first states purpose and usage, then behavioral notes. Every sentence is informative and necessary. No fluff.

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

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

Given no output schema, the description explains what happens after submission (team reads digests, influences roadmap). Parameter count is 3 with 100% schema coverage, and nested 'context' object is explained. The description is sufficient for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description enriches the schema by explaining the 'type' enum with examples, describing 'context' as optional structured context, and giving formatting guidance for 'message'. This adds value beyond plain schema definitions.

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

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

The description clearly states the tool's purpose: sending feedback to Pipeworx about bugs, missing features, data gaps, or praise. It distinguishes between feedback types with specific examples, making it easy for an AI agent to understand when to use this tool.

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

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

The description explicitly states when to use (bug, feature, data_gap, praise) and what not to do (don't paste user prompt). It also mentions rate limits and that it's free. While it doesn't compare to siblings, no sibling tool serves a similar feedback purpose, so this 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: self-aggregating from CF analytics-engine, no PII, and caching duration (5min-1h). 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 well-structured with clear use cases and important notes. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall effective.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It covers what it returns, use cases, caching behavior, and privacy. 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?

The single parameter 'window' has full schema coverage (enum and description). The description adds meaning by explaining how shorter vs longer windows surface different trends ('hot right now' vs 'steady-state demand'), which goes beyond the schema's enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for specified windows (24h, 7d, 30d). The verb 'returns' is specific, and the resource 'trending calls on Pipeworx' is well-defined. It distinguishes from siblings like discover_tools by focusing on aggregate popularity rather than tool 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 lists three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment. While it does not explicitly state when not to use, the context is clear. It could mention alternatives like discover_tools for detailed tool info, but the provided guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral context: monotonicity violation logic, partition check with sum≈1, Jaccard similarity threshold (≥0.30), placeholder filtering, fill check against live CLOB depth, and conditions for not trading. 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 but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded requirement. Every sentence adds necessary detail for a complex tool, though slightly longer than ideal.

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

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

Despite no output schema, the description comprehensively details the response structure (opportunities[], partition_check, fill_check fields). Given the tool's complexity and rich annotations, the description is fully adequate for an agent to understand invocation and interpretation.

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

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

Schema coverage is 100%, but description adds rich meaning: explains event takes slugs or full URLs with examples (e.g., 'fed-decision-may-2026'), topic takes seed questions, and describes the behavior of each parameter in detail, far beyond the schema property 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes single-event mode (event) from cross-event mode (topic), uses specific verbs like 'find' and 'checks', and is distinct from sibling tools like 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?

Explicitly states 'REQUIRES one of event or topic — call with no args fails.' Provides clear guidance on when to use each mode: event for specific market, topic for cross-event scanning. Also directs to polymarket_fill_risk for custom sizing, covering when-not-to-use.

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

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

The description extensively discloses behaviors beyond annotations: it explains the three model families with formulas, thresholds, and response structure. It mentions caching (1h KV), diagnostics for empty segments, and details on edge computation. No contradiction with readOnlyHint, openWorldHint, etc.

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-organized: it leads with the core purpose, then systematically details model families, response fields, knobs, and top-level structure. Every sentence adds value, though the length might challenge quick parsing; however, given the complexity, it is appropriately 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?

The description fully compensates for the missing output schema by detailing the response structure (by_segment, fed_candidates/fed_note, _diagnostics) and key fields (edge_pp_net, kelly_fraction, etc.). It also covers caching and filter behavior, leaving no critical gaps for an agent to use the tool effectively.

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

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

With 100% schema coverage, the description adds substantial extra meaning: it provides defaults, recommendations (e.g., 'bump for very thin partitions'), and rationale for min_partition_leg_kelly. Each parameter's purpose and interplay are explained, enhancing agent understanding beyond the schema.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly targets the use case 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx-based edge detection.

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 usage context by detailing when to apply the tool (e.g., discovering opportunities without paging markets) and explains configurable knobs (min_liquidity, max_spread, etc.) that guide agent decisions. However, it does not explicitly contrast with siblings or state when not to use it, though the unique purpose is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: history bounded by 60-day TTL, decay from daily closes not intraday, snapshot gaps from cache misses, and full response structure. No contradictions.

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

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

Description is comprehensive and front-loaded with purpose, but runs long as a single paragraph. Every sentence serves a purpose; minor improvement would be structuring into sections, but highly efficient given the information density.

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, yet description thoroughly explains return structure (tracked[] with full time-series, first_seen, trend, decay; expired[] with lifespan; snapshot_dates[]). Also covers limitations (TTL, start date, intraday not included). Completely covers what agent needs to use 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 provides 100% coverage with basic descriptions. Description adds context: days default 14, max 30 (clarifying clamp 2-30), window default '1wk' and explains it as snapshot family. This adds meaningful guidance 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 tool measures edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and trend. Distinguishes from sibling polymarket_edges by focusing on historical behavior rather than current edges.

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

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

Provides context on when to use (to understand if an edge is shrinking or stable) and contrasts fresh vs old edges. Does not explicitly state when not to use or name alternatives, but sibling tool polymarket_edges implies where to get 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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral detail: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage, fillable amounts, a verdict (clean/degraded/cannot_fill), and for baskets, theoretical vs realizable sum, capture ratio, profit, thin_legs, and forced directional risk. It warns about partial basket fills converting arb into unhedged positions. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections marked by uppercase labels (SINGLE-MARKET, BASKET, USE THIS). It is front-loaded with the core purpose and uses efficient bullet-point-like listing of return fields. While dense, every sentence adds essential context; minor redundancy might be trimmed, but overall appropriate for the complexity.

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

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

Despite lacking an output schema, the description comprehensively details all return fields for both modes. It covers single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). The usage guidance is also complete with risk explanation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning by explaining the difference between single-market and basket modes, the auto side logic for baskets (sell if partition sum > 1, buy if < 1), and how size_usd is interpreted differently (spend vs target proceeds vs settlement notional). This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes itself from siblings (like polymarket_arbitrage, polymarket_edges) by being a pre-trade risk validation tool. It specifies two modes (single-market and basket) with explicit behavior.

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

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

The description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It provides context on why (theoretical overround not capturable on thin books, partial basket fills convert arb into directional risk). However, it does not explicitly state when not to use it, leaving some ambiguity for lower-value trades.

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, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: compatibility_warning for non-equivalent bet shapes, temporal_alignment checks, skipped_cross_type/subtype counters. 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?

Dense but well-structured: purpose, modes, response fields, safety fields. Front-loaded key information. 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?

Tool is complex with 3 parameters and no output schema. Description covers response format, edge cases, compatibility checks, temporal alignment, and counters. Thoroughly informs the agent about expected behavior and limitations.

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

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

Input schema covers all 3 parameters with descriptions. Description adds value beyond schema by explaining topic values and override behavior. Since schema coverage is 100%, baseline is 3; the added context justifies a 4.

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

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

Description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It explains two modes (topic and explicit) and distinguishes from sibling tools like polymarket_arbitrage which focus on intra-venue arbitrage.

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

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

Explicitly describes when to use topic mode for pre-mapped shortcuts and explicit mode for custom pairings. Warns that most pre-mapped topics are not tradeable, setting proper expectations. Lacks explicit mention of alternative tools for cases when spreads are not meaningful.

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, destructiveHint. Description adds scoping and pairing context without contradicting annotations.

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

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

Three concise sentences, front-loaded with action, then usage guidance, then scoping. No unnecessary words.

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

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

Given low complexity (1 optional param, no output schema, rich annotations), description covers all necessary aspects: purpose, usage, interaction with siblings, and scope.

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

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

Schema covers 100% of the single parameter. Description adds usage nuance (omit to list all keys) and example values, slightly exceeding baseline.

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

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

Clearly states it retrieves a value saved via remember or lists all keys if omitted. Directly 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?

Explicitly describes when to use (look up context stored earlier) and pairing with remember/forget. Also mentions scoping to user identifier.

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: true, meaning the tool does not modify state. However, the description says setting mark_read:true flags events as read, which is a state modification. This is a direct contradiction, so transparency is severely compromised.

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

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

The description is four sentences, each earning its place. It front-loads the core purpose, then adds parameter details, side effects, and alternative access. No wasted words.

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

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

The description covers return fields, parameter usage with examples, the side effect of mark_read, and an alternative access method. However, the contradiction with annotations and lack of explicit contraindications reduce completeness somewhat.

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 value by giving an example filter type ('sec_8k'), explaining mark_read behavior, and noting the limit range (1-200). This extra context improves parameter understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts with specific fields. It distinguishes its scope and mentions an alternative access method (GET endpoint for scripts/dashboards), making its purpose unambiguous.

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

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

The description provides usage clues like polling being fine and the option to mark events read, but it does not explicitly tell when to use this tool over siblings (e.g., list_subscriptions, ask_pipeworx) or when not to use it. The guidance is adequate but not comprehensive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond those: it fans out to multiple sources (SEC EDGAR, GDELT/GNews fallback, USPTO), explains failure modes (GDELT→GNews on rate limit/5xx, USPTO soft-fail until reactivated), and describes output structure. This provides good transparency without contradicting annotations.

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

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

The description is a single dense paragraph, but every sentence adds value. It front-loads the most common usage patterns as example queries, then explains sources, fallbacks, input formats, and output. There is no fluff or repetition. It earns its length.

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

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

Given the tool has three parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It explains all data sources (SEC EDGAR, GDELT, GNews, USPTO) with their conditions, input syntax with examples, output structure (changes grouped by source, total_changes count, citation URIs), and distinguishes from a sibling tool. There are no obvious gaps.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant extra meaning: it provides example values for 'since' (ISO date '2026-04-01' or relative '7d', '30d', '3m', '1y'), clarifies 'value' accepts ticker or zero-padded CIK, and explains that 'type' only supports 'company'. This goes well beyond the schema and fully compensates for any potential ambiguity.

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 multiple example queries ('What's new with X', 'latest on Y', etc.) that make the purpose immediately clear. It specifies the tool provides a change feed for a company over a time window, and explicitly distinguishes itself from the sibling 'entity_profile' tool by saying 'Use entity_profile instead when you want the static profile'. This level of specificity and sibling differentiation meets the highest standard.

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

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

The description clearly states when to use the tool (for recent changes) and explicitly directs to 'entity_profile instead' for static profile, which is an alternative. It gives examples of typical queries. However, it does not explicitly state when NOT to use the tool beyond the static profile case, so it loses one point for not covering all 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?

The description adds significant behavioral context beyond the annotations: it explains scoping by identifier, persistence differences between authenticated users (permanent) and anonymous sessions (24-hour retention), and the key-value storage model. Annotations indicate idempotentHint=true and destructiveHint=false, which are consistent with the description.

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

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

The description is a single, well-organized paragraph of about 100 words. It starts with the core purpose, then context for when to use, followed by technical details (scoping, persistence) and pairing cues. Every sentence adds value without redundancy.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage context, storage mechanism, scope, retention, and integration with sibling tools. It is fully complete given the tool's low 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?

The input schema already has high coverage (100%) with descriptive examples for 'key' and 'value'. The description adds minor context about naming conventions and usage, but does not significantly extend the schema's meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's verb ('save') and resource ('data' as key-value pairs), and explicitly distinguishes it from sibling tools 'recall' and 'forget' by mentioning pairing. It defines the scope and retention behavior, leaving no ambiguity about the tool's 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?

The description provides clear guidance on when to use the tool ('when you discover something worth carrying forward') and mentions pairing with recall and forget. However, it does not explicitly state when not to use it, such as for transient or one-time data, which slightly reduces clarity.

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, and non-destructive behavior. The description adds significant behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also details the return types and auto-disambiguation for company input, which helps the agent understand complexity.

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

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

The description is somewhat long but well-structured: starts with example queries, provides a crisp usage directive, then breaks down supported types with specific output details. Every sentence adds value. A minor trim could improve conciseness, but it remains efficient.

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

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

The tool handles two entity types with complex internal logic and no output schema. The description compensates by detailing what each type returns. However, a formal output schema would reduce ambiguity. Given sibling tools like entity_profile exist for further detail, the description provides sufficient context for agent decision-making.

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. But the description greatly enriches meaning: for type='company', it explains the output includes ticker, CIK, and company_name; for type='drug', it lists RxCUI, ingredient, brand. It also notes that company value can be ticker, CIK, or name with auto-disambiguation. This goes well beyond the schema's simple parameter descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier'. It uses specific verbs like 'resolve', 'look up', 'find the ID for'. It distinguishes itself from sibling tools by emphasizing it is used to obtain IDs required by other tools, and the examples ('ticker', 'CIK', 'RxCUI') make the scope precise.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' This provides strong usage guidance. However, it does not provide explicit instructions on when NOT to use the tool or mention alternative tools for already-resolved entities, which would enhance clarity.

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 non-destructive behavior. The description adds behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. This adds value beyond annotations without contradiction.

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

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

The description is three sentences, front-loaded with the main purpose, then the process, then a concrete use case. Every sentence adds value without redundancy or fluff.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also clarifies the role of parameters like context and models, making the tool's behavior fully understandable for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantics: explains that the first entity is treated as 'subject' for narrative, rest as competitors, and that the tool calls ai_visibility_check. This enriches understanding beyond the schema alone.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility across entities'). It distinguishes from sibling 'ai_visibility_check' which probes a single entity, and implies a different scope than 'compare_entities'.

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?

Description provides a clear use case: competitive AI-marketing audits, e.g., checking if 'Claude knows about us as well as our competitors'. It names the underlying tool 'ai_visibility_check' but does not explicitly state when not to use this tool or list alternatives, though the 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?

Description adds valuable behavioral context beyond annotations, such as parallel fan-out across services, partial failure handling ('sources_failed' lists timeouts), and latency specifics ('bundlephobia's first measurement... can take 5-30s'). No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 three sentences long, front-loaded with purpose, and packed with essential details. Could be slightly more concise, but every sentence contributes unique value (purpose, usage, behavior).

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 fully compensates by listing return fields, explaining failure modes, and specifying scope limitations. Covers all key aspects an agent needs 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?

Schema coverage is 100%, so baseline is 3. Description adds context about package accepting scoped names and version defaulting to latest. It also outlines return fields, providing extra value beyond schema alone.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, scanning deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('dependency'), and the context distinguishes it from sibling tools by specifying the ecosystem scope (npm only).

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

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

Explicit guidance on when to use: 'whenever an agent asks "is X safe / popular / small"'. Also clarifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear 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 (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) already convey safety and idempotency. The description adds the core behavioral trait of substring filtering, but does not disclose other aspects like return format or pagination, though an output schema likely covers that.

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

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

The description is a single sentence with no superfluous words. It is front-loaded and efficiently communicates the essential purpose.

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

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

For a simple one-parameter tool with an output schema and comprehensive annotations, the description is mostly adequate. However, it leaves ambiguity about substring matching behavior (e.g., case sensitivity) and does not clarify if the tool returns full documents or summaries, which could affect agent decisions.

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 0% schema description coverage, the description's mention of 'substring' adds meaning to the 'query' parameter beyond the raw schema. However, it lacks detail on matching rules (case sensitivity, exact vs partial). Examples in the schema provide some compensation, keeping the score at a baseline 3.

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

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

The description 'Filter docs index by substring.' clearly states the tool's action (filter) and resource (docs index) with a specific method (by substring). This precisely differentiates it from sibling tools like search_index or search_within.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or when not to use it, leaving the agent without context for appropriate invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the substring-search nature, but does not detail behavior like result ordering, pagination, or matching scope (e.g., case sensitivity).

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 a single sentence with no wasted words. However, it could add a bit more context without harming conciseness, such as noting that slug identifies the doc.

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 an output schema, the description fails to clarify what 'entries' are or the scope of the search. With three parameters and no schema descriptions, the description is too minimal for an agent to fully understand usage.

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

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

Schema coverage is 0%, so description must explain parameters. It only states 'substring-search entries inside a doc' without elaborating on slug, query, or limit. Parameter names are somewhat self-explanatory, but explicit semantics are missing.

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 substring-search within entries of a doc. The verb 'substring-search' and resource 'entries inside a doc' are specific, and it distinguishes from siblings like search_docs or search_within by specifying substring matching.

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?

No guidance on when to use this tool versus alternatives like search_docs, search_within, or scan_dependency. The description does not provide context about selective use or 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?

The description discloses implementation specifics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. It also notes the return of character offsets and similarity scores. These details go well beyond the annotations (which only indicate readOnly, idempotent, etc.) and fully inform the agent of behavioral traits.

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 about 5 sentences, front-loading purpose and usage, then technical details. Every sentence provides unique value with no redundancy or fluff. The structure is logical and efficient.

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

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

Given no output schema, the description explains returns (passages, offsets, similarity scores) and truncation behavior. It also mentions a companion tool for grounding. However, it does not detail the exact output JSON structure, and it could briefly contrast with search_docs to prevent misuse. Still largely 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 natural-language query examples and reiterates the character cap for the text parameter. It also mentions the default limit of 5 (likely mirrored in schema). This adds useful context but does not dramatically expand on the schema.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article, tool result). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and implying this tool is for searching within a single text, unlike search_docs which searches across documents.

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

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

The description provides clear guidance: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also suggests pairing with ask_pipeworx_grounded. However, it does not explicitly exclude short texts or compare to similar search tools like search_docs or search_index.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: account requirements, delivery channels (feed always on, email/SMS/webhook), webhook signing, SMS verification and cap, auto-disable on failures. 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 well-structured with clear sections, though lengthy. Every sentence adds value, and it front-loads the primary purpose. Slight redundancy could be trimmed, but overall effective.

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

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

Despite no output schema, the description states the return value (subscription ID) and covers types, requirements, delivery options, and limitations. The tool is moderately complex, and the description is complete enough 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?

Schema coverage is 100%, so the schema already documents parameters. The description adds concrete examples for each subscription type, clarifying optional fields and constraints, which enhances usability 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 creates a proactive monitoring subscription and returns a subscription ID. It lists supported types with examples, distinguishing it from related tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context for when to use: requires a Pipeworx OAuth account, and gives type-specific parameters. It does not explicitly say when not to use, but the context is sufficient to guide selection among siblings.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that results are 'drawn from the live catalog of thousands of tools' and explains return structure (category-bucketed). Does not contradict 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 front-loaded with example questions and purpose. It is slightly long but information-dense with no wasted sentences. Could be trimmed slightly but still 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 tool's role as an onboarding entry point, no output schema, and simple parameters, the description fully covers what an agent needs: how to call, what to expect, and when to use it. It is highly complete.

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

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

Schema coverage is 100% (one parameter described). Description adds meaning by listing possible topic values (finance, pharma, etc.) and explaining that omitting topic gives a cross-category spread, which is beyond the schema description.

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

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

The description clearly states it returns 'category-bucketed example questions' and is the 'onboarding entry point'. It uses specific verbs like 'returns' and specifies resource, distinguishing it from sibling tools that serve different purposes.

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

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

Explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' or 'to learn how to call the meta-tools'. Provides guidance on optional topic parameter. No explicit when-not, 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, idempotentHint=true, and destructiveHint=false, which suffice for safety. The description adds no further behavioral context (e.g., pagination, sorting), but does not contradict 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 only 4 words, which is concise but may be too brief to convey necessary details. It could be structured better with minimal expansion.

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 an output schema, the description is too minimal. It does not specify what 'categories' are, how they are structured, or how 'slug' maps to a doc. For a listing tool with one parameter, more context is needed.

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 description does not explain the 'slug' parameter. With 0% schema description coverage, the description should compensate but fails to clarify what a slug is or how to obtain 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 clearly states the action (list) and the resource (categories inside a doc). It distinguishes the tool from siblings like 'docs' and 'entity_profile', though it does not explicitly differentiate.

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?

No guidance on when to use this tool versus siblings such as 'search_docs' or 'entity_profile'. The description lacks context on prerequisites or 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?

The description adds behavioral details beyond annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events. Annotations already indicate non-destructive and idempotent behavior, and the description is consistent.

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

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

Two concise sentences with no extraneous words. Every sentence adds value: purpose, ownership, and effect on data.

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

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

For a simple tool with one parameter, the description covers the essential aspects: action, ownership, impact on data, and linkage to recent_alerts. No additional information is needed.

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

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

Schema coverage is 100%, and the description does not add further parameter details beyond the schema. The baseline of 3 is appropriate as the schema already documents the 'id' parameter adequately.

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 cancels a subscription by ID, and explicitly distinguishes from siblings like 'subscribe', 'list_subscriptions', and 'recent_alerts' by mentioning ownership enforcement and deactivation instead of deletion.

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

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

It specifies ownership enforcement (only your own subscriptions) and notes that historical events remain via recent_alerts. However, it does not explicitly state when not to use or compare to alternatives, though the context is clear.

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

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

The description fully discloses output: 'verdict (confirmed / approximately_correct / refuted / inconclusive / unsupported), extracted structured form, actual value with pipeworx:// citation, and percent delta'. Since annotations already indicate readOnlyHint and idempotentHint, the description adds value by explaining the return format and domain limitations (v1 scope). 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 compact yet thorough, starting with example queries for easy recognition, then stating purpose, scope, and output details. Every sentence contributes information without redundancy.

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

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

Given no output schema, the description comprehensively explains return values and scope. The tool has a single parameter and is well-contextualized with its domain and capabilities, leaving no ambiguity for the agent.

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

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

The single parameter 'claim' is described in the schema with examples. The main description adds context about supported claim types (company-financial) and provides natural-language query patterns, enriching the schema's description and helping the agent formulate proper inputs.

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 'natural-language claim verification against authoritative sources' and gives specific examples like 'Is it true that...' and 'verify the claim that...'. It distinguishes the tool from siblings by noting it replaces 4-6 sequential calls and specializes in company-financial claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides scope limitations (v1 supports company-financial claims). It implies when not to use (non-financial or non-US claims) and highlights efficiency benefits over alternatives.

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