Ons Uk

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by explaining that the default model is free, Anthropic requires an API key with direct payment, and the return format includes per-model details. This extra context goes beyond the annotations without contradicting them.

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

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

The description is a single paragraph of three sentences, front-loading the main purpose. Every sentence adds value: first sentence states the core function, second explains the models and pricing, third describes the output and use cases. 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?

Despite no output schema, the description fully explains the return format (per-model score, confidence, signals, raw_response + combined view). The four parameters are clearly described in the schema and supplemented by the description. The tool's purpose, inputs, output, and use cases are comprehensively 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%, so baseline is 3. The description adds meaning by explaining that the '_apiKey' is passed straight through to Anthropic and that 'context' helps disambiguate common names. This provides clarity beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It specifies the default model and the option to use Anthropic with a BYO key. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' by focusing on individual entity visibility rather than competitor scanning.

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 indicates the tool is useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring. While it doesn't explicitly state when not to use it or list alternatives, the context is clear and sufficient for most agents to decide applicability.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds value by explaining the routing mechanism (3,668 tools across 860 sources) and return type (structured answer with stable pipeworx:// citation URIs). 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?

Front-loaded with key guidance ('PREFER OVER WEB SEARCH'), then domains and examples. While long, every sentence is useful. Could be slightly more concise 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?

No output schema exists, but description only vaguely mentions 'structured answer with citation URIs.' For a tool with many siblings and no output schema, more detail on return format would improve completeness.

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

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

Schema coverage is 100% and description does not add extra meaning beyond what the schema already provides (natural language question field and aliases). 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 answers factual questions from structured sources, using specific verbs like 'ask' and resource 'Pipeworx'. It distinguishes itself from web search and lists example domains and queries, making 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?

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance: for factual questions, specific domains (SEC, FDA, etc.), and example patterns. It also implies when not to use (non-factual) and suggests alternatives (web search).

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant value by detailing the refusal mechanism (specific refusal_reason strings), the constraint of using only tool result data, and the extra LLM call cost. 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 comprehensive but slightly long. Every sentence adds value, explaining purpose, behavior, and usage trade-offs. It is well-structured and front-loaded with the key concept, but could be trimmed slightly without losing clarity.

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?

Considering the tool's complexity (routing, extraction, refusal modes) and the absence of an output schema, the description fully explains return format, success/error states, and use cases. It compensates for missing output schema with detailed behavioral info.

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

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

Schema description coverage is 100%, with clear parameter descriptions for 'question' and aliases. The description does not add new semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, explicitly contrasting with ask_pipeworx and detailing the extraction process. The verb 'answer' and resource 'Pipeworx queries' are specific and differentiated from siblings.

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 on when to use this tool (high-stakes, answers to be quoted/cited/acted on) and when to prefer the sibling ask_pipeworx (casual lookups). It also notes the extra LLM call cost, enabling informed selection.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds substantial behavioral context beyond that: it details resolution and classification, fan-out to data sources, response structure, safety short-circuits for low-confidence matches and closed markets, handling of wide spreads, and parent event extraction. No contradictions with annotations.

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

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

The description is very long and dense, with many details like classifier lists, fan-out examples, response shapes, resolver contract, and edge cases. While informative, it is not concise; it could be restructured or shortened to front-load the essential purpose and usage.

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, the existence of 3 parameters with complete schema descriptions, no output schema, and rich annotations, the description is remarkably thorough. It covers input formats, the resolution pipeline, classification, fan-out logic, response structure, safety mechanisms, and edge cases (closed markets, wide spreads). An AI agent would have all necessary context to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing context on when to use each parameter (e.g., 'When false (recommended)...' for include_raw, and it implicitly explains the depth parameter's effect through fan-out examples). However, much of the parameter information is already in the schema.

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

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

The description opens with a very specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states what the tool does, and the usage examples ('should I bet on X', 'what does the data say about Y') help distinguish it from sibling tools like polymarket_edges or ask_pipeworx.

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

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

Explicit usage guidance is provided: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' This clearly indicates when to use the tool. It does not explicitly list when not to use it, but the context is strong enough for an AI agent to differentiate from 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 declare readOnly, openWorld, idempotent, not destructive. Description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, handling of off-calendar fiscal years, and return of paired data with citation URIs. 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 long but every sentence adds value. It is front-loaded with examples, then instructions, then details. No redundant or tautological content. Efficiently packed with 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 fully informs about return structure: paired data, sorted by primary metric, with citation URIs. Covers both entity types, data sources, and edge cases like fiscal year handling. Complete for the tool's purpose.

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 coverage is 100% and uses enums. Description goes beyond schema: explains type values ('company' vs 'drug') with exact data fields each pulls, and clarifies values format (tickers/CIKs for companies, names for drugs). This adds significant 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 uses specific verbs like 'compare', 'rank', 'head to head' and clearly states the tool does side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from siblings like entity_profile by advising to prefer this over sequential single-pack 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?

Explicitly tells when to use: for comparisons of 2-5 entities, and to prefer over sequential lookups. Provides example queries and explains the two entity types. No exclusion criteria needed because scope 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, destructiveHint=false, so the agent knows this is a safe read operation. The description adds no behavioral context beyond 'metadata', 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 very short (three words), but lacks necessary detail. It is not optimally concise as it omits important information; however, it is not verbose.

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

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

Given the simplicity (1 param, output schema present, rich annotations), the description is still incomplete. It fails to provide usage guidelines or parameter context, leaving the agent to infer too much.

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 must compensate by explaining the 'id' parameter. It only says 'Single dataset metadata.' and adds no meaning beyond the schema. The agent is left without guidance on the format or source of the id.

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 'Single dataset metadata.' clearly indicates the tool retrieves metadata for one dataset, distinguishing it from sibling 'datasets' which likely lists all datasets. The verb 'get' is implied, and the resource is specific: metadata for a single dataset.

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 no guidance on when to use this tool versus alternatives like 'datasets' (plural), 'series', or 'editions'. No prerequisites or context are mentioned.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description only adds 'publicly available', which is a minor clarification. No additional behavioral details (e.g., pagination, response format) are disclosed.

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, very concise. However, it is so brief that it sacrifices necessary detail. It front-loads the purpose but could be restructured to include more context without adding 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?

For a simple listing tool with an output schema and comprehensive annotations, the description might be minimally acceptable. However, given the existence of sibling tools like 'dataset' and the lack of parameter explanations, the description is incomplete for effective tool selection and invocation.

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

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

Schema coverage is 0% (no parameter descriptions), and the description does not mention the two parameters (limit, offset) or explain their purpose. This leaves the agent without any semantic guidance beyond parameter names and types.

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 lists publicly available datasets. The verb 'List' and resource 'datasets' are specific and direct. However, it does not differentiate from the sibling tool 'dataset' which likely handles a single dataset, missing an opportunity to clarify scope.

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

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

No guidance is provided on when to use this tool versus alternatives like 'dataset' or 'discover_tools'. The description lacks context about the intended use case or limitations.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly, which is useful behavioral context beyond annotations.

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

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

Four sentences, each serving a distinct purpose: purpose, use cases, return value, usage guidance. No redundancy, well structured, and front-loaded.

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

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

Covers purpose, usage, return format, and example queries. Could mention pagination or default limit but limit parameter is described. Good completeness for a tool discovery function.

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 further clarifies that multiple aliases (q, task, search, description) are accepted, along with example queries, adding value beyond 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 'Find tools by describing the data or task' and enumerates many specific domains (SEC filings, FDA drugs, etc.), distinguishing it from all sibling tools which are specific data or action tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools and want to see the option set', giving clear context for when to use. Lacks explicit when-not-to-use but 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?

While annotations declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, the description adds no behavioral context beyond the name. It does not explain what 'editions' are or how the tool interacts with them, such as whether it returns a list or a single edition.

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 short but lacks informational density. Conciseness should not come at the cost of clarity; here it is under-specified and fails to convey essential details.

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

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

Given the complexity implied by having an output schema and the presence of sibling tools, the description is completely inadequate. It does not explain return values, use cases, or how to interpret results, leaving a significant gap 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?

With 0% schema description coverage, the description must compensate but fails to explain the 'id' parameter. It does not specify whether 'id' refers to a dataset ID, edition ID, or something else, providing no semantic guidance beyond the schema's empty structure.

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 'Editions of a dataset' essentially restates the tool's name and title without specifying what action the tool performs. It gives no verb or indication of whether it lists, retrieves, or manages editions, making it too vague for an agent to understand 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 provides no guidance on when to use this tool versus its siblings like 'dataset' or 'datasets'. There is no mention of context, prerequisites, or alternatives, leaving the agent without direction.

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. The description adds significant behavioral details beyond these: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific data fields (CIK, filings with URIs, fundamentals sorted by period_end, patents, news, LEI); notes that USPTO PatentsView API sunset May 2025 and soft-fails. No contradiction with annotations.

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

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

The description is front-loaded with example queries, making the purpose immediately clear. While it is somewhat long, every sentence adds value (source details, fallback behavior, input constraints). Could be slightly more concise, but the structure is 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?

With no output schema, the description compensates by listing exactly what is returned (CIK, company_name, recent_filings, fundamentals, patents, news, LEI) and explaining behavior (parallel call, USPTO sunset soft-fail). It covers both required parameters and their constraints, and provides enough context for the agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: clarifies that 'value' must be a ticker or zero-padded CIK, not a name, and suggests using resolve_entity first for names. It also notes that the 'type' enum currently only supports 'company' with person/place coming soon.

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 creates a 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example phrases ('Tell me about X', 'research Acme', etc.) and distinguishes itself from sibling tools like 'resolve_entity' and 'compare_entities' by specifying it handles tickers/CIKs directly and is preferred for holistic views.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view.' Also provides clear guidance on when not to use: 'Names not supported — use resolve_entity first if you only have a name.' This directly helps the agent decide between this tool and siblings.

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

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

Annotations already indicate destructive and idempotent. Description adds context about what gets destroyed (memories) and reasons (stale context, sensitive data), enhancing transparency beyond annotations.

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

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

Two sentences, front-loaded with verb, no filler; every sentence adds value.

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

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

Given simple tool with single parameter and no output schema, description covers purpose, usage, and pairing; no gaps.

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

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

Schema coverage is 100% and description does not add meaning beyond the schema; just restates 'by key'. 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?

Describes a specific verb and resource: 'Delete a previously stored memory by key'. Distinguishes from siblings by mentioning pairing with remember and recall.

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

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

Explicitly states when to use: 'context is stale, task is done, or you want to clear sensitive data'. Also names alternative/partner 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 details the internal behavior: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds value beyond annotations (readOnlyHint, idempotentHint) by explaining the actual process and output format.

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

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

The description is concise with three sentences: purpose, process, and use cases. It is front-loaded with the primary action and does not contain wasteful repetition.

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

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

Given no output schema, the description explains the output format (single text blob for site-root/llms.txt). It covers parameters, use cases, and the overall process. Combined with rich annotations, the description is fully complete for a simple tool.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description does not add significant additional meaning for either parameter, remaining at baseline 3. It does not mention max_links or provide extra detail beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (AI crawler indexing). It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on creation rather than visibility checking.

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 specific use cases (getting a client's site indexed, drafting llms.txt, auditing competitors), providing good context for when to use the tool. However, it lacks explicit guidance on when not to use it or mention of alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds no behavioral context beyond stating the output is metadata. It does not discuss prerequisites, side effects, or constraints like date ranges.

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 overly terse (one sentence) and sacrifices necessary detail for brevity. It does not front-load key information or provide a clear structure.

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

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

Given the tool has 3 parameters with no schema descriptions and an existing output schema, the description should at least outline what the metadata contains or how parameters affect results. It is incomplete.

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%, yet the description provides no explanation of the three parameters (id, edition, version). It fails to compensate for the lack of schema descriptions.

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

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

The description 'Latest observation data file metadata' lacks a clear verb and does not specify what the tool does (e.g., retrieve, list). It vaguely restates the name and does not distinguish from sibling tools like 'dataset' or 'series'.

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 provided on when to use this tool versus alternatives. Siblings include similar data retrieval tools, but the description offers no context for selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds value only by specifying the default filter for active subscriptions. It 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 two sentences: first conveying purpose and return fields, second providing usage guidance. Every sentence is essential and there is 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 the tool's simplicity (one optional parameter, no output schema), the description covers all needed context: what it returns, default behavior, and when to use. The parameter is fully explained in the 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?

With 100% schema coverage, the schema already describes the 'include_inactive' parameter. The description does not add further parameter meaning, meeting the baseline expectation.

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

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

The description clearly states the tool lists active subscriptions and details the returned fields (id, type, etc.). It distinguishes itself from sibling subscription management tools like subscribe and unsubscribe.

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

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

The description provides explicit usage scenarios: reviewing subscriptions before adding more or finding an id to cancel. It does not mention when not to use or alternatives, but the context is clear.

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

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

The description adds extensive behavioral context beyond annotations: it's free, rate-limited to 5 per identifier per day, doesn't count against tool-call quota, digests are read daily, and signal affects roadmap. Annotations only provide readOnly, openWorld, idempotent, destructive hints, so the description carries the full burden and delivers.

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

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

The description is a single paragraph but well-structured: purpose first, then usage conditions, then input details, then team processes, then limitations. Every sentence earns its place, and the format is front-loaded.

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

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

The tool has 3 parameters (2 required) and a nested object, but no output schema. The description covers all necessary aspects: what to send (type, message, context), how to format, what happens to the feedback (digests, roadmap impact), and constraints (rate limit, free). This is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for each parameter, but the description adds significant extra meaning: it explains the type enum with examples, recommends message length (1-2 sentences, 2000 chars max), and clarifies the context object purpose. This goes well beyond the schema's baseline.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell the Pipeworx team something is broken, missing, or needs to exist') and distinguishes itself from sibling tools, which are primarily data retrieval tools.

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

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

The description provides explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and includes explicit exclusions: 'don't paste the end-user's prompt.' It also mentions rate limits and that it's free, giving complete context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds crucial context: data source (CF analytics-engine), no PII, cached 5min-1h, and aggregation details.

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

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

Three well-structured sentences with bullet-like use cases. No extraneous information. 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 tool with one parameter and no output schema, the description covers all necessary information: what is returned, window options, use cases, caching, and data privacy.

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

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

Schema has 100% coverage with a description for the only parameter 'window'. Description adds semantic guidance: shorter windows surface what's hot, longer windows show steady-state demand.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It provides three specific use cases, distinguishing it from sibling tools like discover_tools.

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

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

Explicitly lists three scenarios for use (discovery, confirmation, alignment). Does not mention when not to use or directly compare with siblings, but context implies it's for trend discovery.

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 as true, and destructiveHint false. The description adds substantial behavioral context: requirement for one of event/topic, Jaccard similarity threshold for cross-event, partition placeholder filter, and details of the checks performed (monotonicity, partition_check). 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 comprehensive and front-loaded with the critical requirement. While it is lengthy, every sentence adds value. Could be slightly more concise, but the detail is 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?

Given the complexity of the tool (two modes, filtering, similarity checks, partition checks) and the absence of an output schema, the description thoroughly explains behavior, constraints, and output structure, including edge cases like no args, skipped_low_similarity, and placeholder filtering.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema by providing usage recommendations, examples (e.g., 'fed-decision-may-2026'), and explaining the behavior of each parameter in the context of the tool's logic. This enhances understanding for the agent.

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

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

The description clearly identifies the tool as finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and the title and name align well. Sibling tools like polymarket_edges and polymarket_kalshi_spread are related but differentiated.

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

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

Explicitly provides when to use each mode: event for a specific market, topic for cross-event scanning. Warns that calling with no args fails. Explains what cross-event catches that single-event misses, including semantic anchor and partition filter criteria.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: caching (1h), model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculations, Fed data limitations, and diagnostic output. 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 extremely detailed and information-dense, covering model families, Kelly calculations, filters, and diagnostics. While well-structured with clear segmentation, it is verbose and could overwhelm agents seeking quick understanding. The core purpose is front-loaded, but the wall of text reduces conciseness.

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

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

Given the complexity (9 parameters, no output schema), the description is remarkably complete: it explains the output structure (by_segment, diagnostics), caching behavior, parameter interactions, edge cases (Fed data caveat), and provides example values. It leaves minimal ambiguity for agent invocation.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: it explains how each knob affects opportunity selection (e.g., min_liquidity as 'tradeable-edge filter'), provides example values, and clarifies edge cases (e.g., min_partition_leg_kelly for partition arbs). This exceeds the schema's simple 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market prices. It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear context for when to use it. However, it does not explicitly contrast with sibling tools or provide 'when not to use' guidance beyond implied specialization.

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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds extensive context: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains behavior when compatibility warning is triggered. No contradiction with annotations.

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

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

The description is long but front-loaded with core purpose. Every sentence adds value, but some details (e.g., detailed explanation of skipped_cross_type) could be more concise. Still structured with clear separation of modes, response, and safety fields.

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

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

Given the complexity (cross-venue, multiple modes, safety fields), the description is very thorough. It explains response fields, safety checks, and temporal alignment. No output schema, so description must explain return values, which it does adequately.

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 each parameter. The description adds meaning beyond schema by explaining the two modes (topic as macro shortcut, explicit ticker/slug) and how parameters override each other. Provides examples in schema. Could be slightly more concise but adds useful context.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like `polymarket_arbitrage` and `polymarket_edges` by focusing on cross-venue spread. Details two modes (topic vs explicit) and provides examples.

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

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

Explicitly states when to use (comparing prices across venues) and when not to (when compatibility warning fires). Provides clear guidance that pre-mapped topics often are not tradeable and warns about non-equivalent bet shapes. Includes details on safety fields and temporal alignment.

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 read-only, idempotent, non-destructive. Description adds scope (per identifier) and pairing with remember/forget, adding value 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?

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

Fully explains dual behavior, scope, and usage patterns. No gaps given the simple tool signature and comprehensive annotations.

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

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

Schema covers the single optional parameter with description. Description clarifies that omitting key lists all keys, adding behavioral semantics beyond schema.

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

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

Clearly states it retrieves a value saved via remember or lists all keys if omitted, distinguishing it from siblings like remember and forget.

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

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

Provides explicit when-to-use scenarios (look up context such as ticker, address, notes) and notes scope, but lacks explicit when-not-to-use or alternative tools besides remember/forget.

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

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

The description reveals that mark_read:true modifies state (flags as read), which contradicts the annotation readOnlyHint=true. According to rules, contradiction yields score 1.

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?

Five concise sentences, front-loaded with purpose, each sentence adds unique information. No fluff.

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

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

Covers purpose, filtering, mark_read behavior, and alternative access. Missing explanation of unread_only parameter, but parameters are well-documented in schema. Good overall for a read-oriented tool.

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

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

Schema coverage is 100%, baseline 3. The description adds value with an example for type ('sec_8k'), explains mark_read behavior, and describes event fields. Exceeds baseline.

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

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

The description clearly states the tool pulls fired events from a subscription feed, lists key fields (source, citation_uri, payload), and mentions filtering capabilities. It is specific and distinct from sibling tools like list_subscriptions or remember.

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

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

It provides context on when to use (polls) and mentions an alternative access method (direct URL). However, it does not explicitly contrast with sibling tools or state when not to use.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains the GDELT/GNews fallback mechanism, notes USPTO soft-failure due to API sunset, and outlines the return structure (changes[] grouped by source + total_changes + citation URIs). 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 a single dense paragraph, but every sentence adds value. It is front-loaded with example queries, then explains behavior, then parameter details, then return structure. Slightly more structure (e.g., bullet points) could improve readability, but it is concise and efficient for its wealth of information.

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

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

Given the tool's complexity (fanned-out multi-source queries, fallback logic, error handling for USPTO, return format with grouped changes and citation URIs), the description provides a complete picture. There is no output schema, but the description sufficiently describes the output structure. All essential 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%, so the baseline is 3. The description adds extra meaning beyond the schema: it expands on the 'since' parameter with examples of both ISO date and relative shorthand ('7d', '30d', '3m', '1y') and provides a practical recommendation for monitoring. This enhancement justifies a score of 4.

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

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

The description opens with concrete use-case examples ('What's new with X', 'latest on Y', etc.), specifies the verb ('change feed for a company in the last N days/weeks/months'), and explicitly contrasts itself with the sibling tool 'entity_profile' which returns static profiles. This makes the tool's purpose immediately clear and distinguishable.

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 on when to use this tool (e.g., 'updates on Acme', 'news on Tesla recently') and when to use the alternative ('Use entity_profile instead when you want the static profile'). It also includes practical recommendations such as 'Use "30d" or "1m" for typical monitoring.'

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 scoping by identifier, persistence differences (authenticated vs anonymous 24hr), and pairing behavior beyond annotations. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Four sentences, each adds value. Purpose is front-loaded. No redundant information. Efficient and clear.

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

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

With 2 fully described parameters and no output schema, the description covers storage behavior, scoping, and integration with sibling tools, leaving no gaps 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?

Schema covers 100% with clear descriptions. Description adds contextual examples (e.g., 'subject_property', 'target_ticker') but does not add new syntax or format details beyond what the schema provides.

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?

Specific verb 'Save' with resource 'data the agent will need to reuse later', includes examples of what to store, and distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, and gives usage context across sessions and conversations.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds valuable context about internal cascading lookups and detailed return fields (ticker, CIK, RxCUI, citation URIs), going 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?

Well-structured with front-loaded purpose and detailed type breakdown. Minor redundancy possible but each section serves a purpose; overall 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?

Covers return values for both entity types despite no output schema, includes citation URIs. Complete for a resolve tool given complexity and sibling context.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds examples and notes auto-disambiguation, providing extra clarity 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 the tool resolves names to canonical identifiers, with example queries and supported types. However, it lacks explicit differentiation from sibling tools like 'entity_profile' or 'compare_entities', which may also involve identifiers.

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 to use 'FIRST' when needing an ID, with concrete examples. Does not mention when not to use or suggest alternatives, but context is clear.

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

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

Annotations already indicate read-only, idempotent, open-world hint. The description adds process details: probes each entity with ai_visibility_check, ranks by score, surfaces extremes. It also mentions output fields (score, confidence, signal density). 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?

Three sentences: purpose, process, example use case. Front-loaded with the main verb and resource. No unnecessary words. Every sentence adds distinct value.

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

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

Given no output schema, the description names the output fields (score, confidence, signal density). It explains input constraints (2-8 entities), models, and context. The process is clear. Could detail output format more, but sufficient for an AI agent.

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

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

Schema coverage is 100%, but description adds context: first entity is 'subject', models supported (workers-ai, anthropic), context disambiguates, and API key purpose. This enriches understanding beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, specifies the verb 'compare', the resource 'AI visibility', and distinguishes it from siblings like the single-entity ai_visibility_check tool. The detail of probing each entity with ai_visibility_check and ranking by score removes ambiguity.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' and an example question. It implicitly guides use over sibling tools by describing a side-by-side comparison, but does not explicitly state when not to use or name alternatives. The context makes it easy to infer.

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 (readOnly, etc.), the description discloses partial failure behavior, that bundlephobia's first measurement can take 5-30s, and that sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage, but it is somewhat verbose with many specific details. Still, it is well-structured and every sentence adds value.

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

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

No output schema, but the description thoroughly explains what the tool returns (summary block, advisories, links, alternative versions) and handles edge cases like partial failures and timeouts. Complete for a composite 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 covers both parameters with descriptions; description adds that scoped packages are accepted and version defaults to latest. Since schema coverage is 100%, baseline is 3, and the added info is minor.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering safety, popularity, and size. It distinguishes from sibling tools by explicitly noting the NPM-only scope and directing other ecosystems to deps.dev.

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: when an agent asks about npm package safety/popularity/size. Also gives when-not-to-use: for other ecosystems like PyPI, Maven, etc., use deps.dev directly. This helps the agent choose correctly.

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 annotations: it reveals the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag). Annotations already indicate safe read-only operation, so 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 two sentences, front-loaded with the core purpose, and each sentence adds essential information. No wasted words; efficient and clear.

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

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

Given no output schema, the description compensates by explaining the return format (top-N passages with offsets and similarity scores). It also covers edge cases (truncation flag) and provides implementation details. For a tool with 3 parameters and rich annotations, the description is complete.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the 'text' parameter as 'the text you already pulled' and gives example queries for the 'query' parameter. For 'limit', it restates the schema but adds no new insight. Overall, it enriches 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 that search_within performs semantic search inside a fetched record, using specific examples like SEC 10-K or article. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and implicitly differentiating from other search/retrieval tools.

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

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

The description provides clear guidance on when to use: when a record is too large for the prompt. It explains benefits (saves context, returns relevant passages with offsets). It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use or list alternative tools, though the sibling list is available.

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, and destructiveHint. Description adds no behavioral context beyond what annotations convey, missing opportunity to explain data source characteristics or behavior.

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

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

Single sentence of 4 words is extremely concise, but lacks any structural elements like bullet points or sections. Every word earns its place, but could benefit from slight expansion for clarity.

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 (1 param, output schema exists, rich annotations), the description is minimally adequate. However, it misses context like what the time series contains (e.g., data points, metadata) or typical use cases, making it slightly below complete.

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

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

Schema coverage is 100% with a clear description of the 'uri' parameter. Description adds no additional semantic value beyond the schema, meeting the baseline expectation.

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 returns a time series by ONS URI. Though minimal, it distinguishes from sibling tools like 'dataset' or 'latest_observations' by specifying the resource type. Missing context on what ONS stands for, but sufficient for purpose identification.

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

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

No guidance on when to use this tool versus siblings like 'dataset' or 'editions'. Agents have to infer from the name and URI pattern. No exclusion or alternatives mentioned.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, persistent subscriptions, delivery channel caps (10/day for SMS), and always-on feed. This complements the annotations (idempotent, not destructive) 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 front-loaded with the core purpose and return value, then systematically covers prerequisites, supported types with examples, and delivery options. 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?

Given the tool's complexity (3 parameters, nested objects, multiple types, delivery options, auth requirement), the description covers all essential aspects: what it does, prerequisites, type-specific parameters, delivery channels, and output. No gaps identified.

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

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

With 100% schema coverage, the description adds substantial meaning by providing type-specific examples (e.g., sec_8k with items, fred_series with series_id) and explaining delivery channel limitations. This goes well beyond the schema's 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying creation action.

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 context on when to use (proactive monitoring) and prerequisites (OAuth account). It also mentions alternatives for pulling feeds (recent_alerts or GET endpoint). However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: returns example questions with exact tool+argument shape, drawn from a live catalog. 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 slightly long but well-structured, front-loaded with common queries and then detailing output. Every sentence adds value, but could be slightly more concise.

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

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

Given no output schema, the description fully explains return content (category-bucketed example questions with tool+argument shape) and covers usage for topic filtering. Complete for an onboarding tool.

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

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

Schema coverage is 100% with one parameter 'topic'. The description adds meaning by listing valid focus areas and explaining that omitting returns a cross-category spread, exceeding 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's purpose: it's an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and distinguishes from siblings like 'ask_pipeworx' by noting it's for learning what Pipeworx can do.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains calling with no arguments vs. specifying a topic, providing clear when-to-use context.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds that the row is deactivated (not deleted) and ownership is enforced, providing useful behavioral context beyond annotations.

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

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

Two sentences, each earning its place: the first states the action, the second details constraints and effects. No wasted words, front-loaded 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 and no output schema, the description fully covers purpose, ownership, and effect (deactivation). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, with the id parameter described as 'Subscription id (uuid) returned by subscribe.' The description reinforces this by saying 'by id' and implies the source, adding meaning.

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

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

The description clearly states the action 'Cancel a subscription by id,' using a specific verb and resource. It distinguishes this from sibling tools like 'subscribe' and 'list_subscriptions' by indicating cancellation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear usage constraint. It does not explicitly list alternatives or when-not to use, but the context against siblings 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, indicating a safe, idempotent read operation. The description adds valuable behavioral context: the tool uses SEC EDGAR + XBRL sources, returns a verdict with structured fields and a citation, and replaces multiple sequential calls. It 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 a single focused paragraph of around 120 words, front-loaded with purpose and trigger phrases. Every sentence is informative, covering what it does, when to use, scope, and return format, without unnecessary repetition.

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

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

Given no output schema, the description fully explains the return value (verdict types, structured form, citation, percent delta). It also covers the domain, limitations (v1, company-financial), and how it integrates with other tools, making it complete for an agent to use.

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

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

The single parameter 'claim' has 100% schema description coverage with examples. The tool description further enriches understanding by specifying the claim domain (company-financial) and the sources used, adding meaning beyond the schema. The baseline of 3 is increased due to this helpful context.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically company-financial claims. It uses multiple trigger phrases ('fact check', 'verify the claim') and distinguishes from sibling tools by explicitly noting it replaces 4-6 sequential calls, making its role unique.

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 when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported domain (company-financial claims for US public companies). However, it does not explicitly exclude alternatives like ask_pipeworx for non-financial claims, so it lacks exclusions.

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