Unicode

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 value by explaining the default model (free), the requirement for an Anthropic API key for that model, and the return format (per-model fields plus combined view). This provides useful behavioral context 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 concise (two informative sentences plus use cases) and front-loaded with the primary action. Every sentence adds value, and there is no redundancy or unnecessary detail.

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

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

Given that the tool has no output schema, the description provides a good level of completeness: it specifies the input parameters, default behavior, the requirement for an API key, and the structure of the return object. It does not detail the combined view but is sufficient for an agent to understand the overall functionality.

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

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

Schema coverage is 100% with descriptive parameter descriptions (entity, models, _apiKey, context). The description's additional text about default model and API key mostly repeats what is already in the schema. Thus, it adds only marginal semantic value beyond the schema.

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

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

The description clearly states the tool's action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and the use cases at the end help distinguish it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides clear context for when to use the tool, listing use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, it does not explicitly exclude scenarios or compare to sibling tools, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description's burden is lower. The description adds valuable context: it routes to one of many tools, fills arguments, and returns structured answers with pipeworx:// citation URIs. However, it doesn't discuss potential limitations or rate limits.

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: it opens with a strong directive, lists domains, explains behavior, gives examples, and compares to siblings. Every sentence adds value, though some repetition exists (e.g., 'START HERE' and 'PREFER OVER WEB SEARCH' overlap slightly). It is appropriately sized for a tool with high 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 no output schema, the description compensates by stating it returns structured answers with citations. It explains the routing behavior, provides usage examples, and covers when to use alternatives. Combined with rich annotations (readOnly, openWorld, idempotent), the description is fully complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with all six parameters clearly documented as aliases for the 'question' field. The description adds an example list but does not provide additional semantic meaning beyond what the schema already conveys. Baseline of 3 is appropriate.

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

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

The description explicitly states that the tool is a question router for factual data, listing specific domains and clearly distinguishing it from siblings like ask_pipeworx_grounded and deep_research. It uses strong verbs like 'routes' and 'returns' with a specific resource (4,552 tools across 1,160 sources).

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use with alternatives ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also gives concrete query examples.

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

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

Discloses significant behavioral traits beyond annotations: same routing as `ask_pipeworx`, extraction from tool result only, return format with fields like `answer`, `evidence`, `confidence`, and specific refusal reasons. Also notes extra LLM call cost.

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 relatively long but front-loads critical details (purpose, routing, return format) and each sentence earns its place. Could arguably be slightly shorter but is well-structured for the tool's complexity.

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

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

Given no output schema, the description fully covers return format, refusal reasons, cost implications, and usage context. It is thorough enough for an agent to invoke correctly without additional ambiguity.

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 minimal new meaning—merely clarifies that all five parameters are aliases for `question`. This is helpful but does not improve parameter 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling `ask_pipeworx` by explaining it extracts answers only from tool results. The purpose is specific and well-defined.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Also lists refusal reasons that inform decision-making.

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 carries a lighter burden but still adds significant behavioral context. It details response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk, going well beyond annotations.

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

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

The description is very long and contains a lot of detail, which is necessary for a complex tool. It is front-loaded with the core purpose and structured with sections, but some redundancy and excessive detail could be trimmed. Overall, it's adequate but not concise.

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

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

Given the tool's complexity, the description covers all aspects: input, output shape, edge cases (low-confidence matches, closed markets, wide spreads), safety mechanisms, and resolution rules. No output schema is present, so the description compensates fully.

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 further context, such as depth options ('quick' vs 'thorough'), include_raw consequences, and examples of market input formats. This adds 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 clearly states the tool researches Polymarket bets by pulling Pipeworx data. It lists specific input formats (slug, URL, question text) and provides explicit use cases like 'should I bet on X'. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges which have 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?

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not provide explicit when-not-to-use scenarios or mention alternatives among siblings, though the context implies it's for individual bet research.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds behavioral details like the 64-character limit, offline operation, and the exact output fields. This provides useful context 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 two sentences: the first states the core function and limit, the second lists outputs. Every word adds value, and it is front-loaded with the most important 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 that there is no output schema, the description thoroughly explains the return values (Unicode code point, UTF-8 byte sequence, etc.). It also covers the character limit and offline nature, making the tool's behavior fully understandable.

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 covers the 'text' parameter with 100% description coverage. The description adds meaning by specifying a 64-character upper limit, which is not in the schema. This helps agents understand constraints.

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 what the tool does: inspect each character of a string. It lists specific outputs (Unicode code point, UTF-8 byte sequence, etc.), which distinguishes it from sibling tools like escape_string or unescape_string that handle string transformations.

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

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

The description mentions a character limit of 64 and states 'Keyless, offline,' implying no external dependencies. However, it does not explicitly state when to use this tool over alternatives or when not to use it. The context is clear enough for the intended purpose.

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, idempotentHint=true. The description adds significant behavioral context: it details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), explains off-calendar fiscal year handling, states that results are sorted by primary metric, and mentions citation URIs. This goes well beyond the annotations.

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

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

The description is well-structured, starting with example queries followed by usage preference, then details per type. It is slightly verbose but each sentence adds value. No wasted words.

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

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

Given the complexity (two entity types, multiple metrics, sorting) and no output schema, the description covers what the tool returns (paired data, citation URIs, sorted results). It could be slightly more explicit about output format, but it is generally complete. Annotations cover safety aspects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains what data is pulled for each type (e.g., revenue, net income for companies) and gives concrete examples for the values parameter (tickers or drug names).

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

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

The description clearly states the tool's purpose: performing side-by-side comparisons of 2-5 companies or drugs in a single call. It uses specific verb examples like 'compare X and Y', distinguishes between entity types (company vs. drug), and explicitly differentiates from 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?

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage context. It also gives example queries and constraints (max 5 entities). However, it does not explicitly name alternative tools like entity_profile, though siblings list them.

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

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

The description goes beyond annotations by detailing account requirements, paid plan for thorough depth, expected response time (15-60s), and returns gaps when topic not in catalog. 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 informative but somewhat lengthy. It front-loads critical account information and uses clear structure. Could be slightly more concise but remains 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 (many data sources, parallel execution) and lack of output schema, the description is highly complete. It covers input semantics, behavioral quirks, limitations, and alternatives comprehensively.

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 value by explaining depth enum meanings (quick=3, standard=5, thorough=8) and clarifying that question accepts natural language and multi-part queries.

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

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

The description clearly states the tool performs multi-source structured data research in one call, distinguishing it from siblings like ask_pipeworx. It specifies verb 'research' and resource 'structured data sources' with explicit scope and sibling differentiation.

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

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

The description provides explicit when-to-use guidance (broad/multi-part questions over structured data) and when-not-to-use (breaking news, current events) with named alternatives (ask_pipeworx). Also covers account and plan prerequisites.

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 safe, idempotent behavior. Description adds that it returns top-N relevant tools with full input schemas and curated examples, ready to call directly with no second lookup. This adds behavioral 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?

The description is informative but efficiently structured: first sentence states purpose, then usage examples, output details, and when to call. Every sentence adds value, though slightly long.

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 6 parameters (many aliases), 1 required, full schema coverage, and no output schema, the description explains output thoroughly: returns top-N tools with names, descriptions, full input schemas with examples. It also explains aliases and limit. Complete for this 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 examples of natural language queries and clarifies aliases for query (q, task, search, description) and limit defaults. This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists many example domains, and distinguishes it from siblings by recommending calling it first when you want to see the option set. The verb 'discover' and the resource 'tools' are specific.

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

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

Explicitly says 'Call this FIRST... when you have many tools available and want to see the option set (not just one answer).' Provides examples of when to use: browse, search, look up. Does not explicitly state when not to use, but guidance 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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds critical behavioral details: fans out across multiple sources, explains patent soft-fail due to USPTO sunset, specifies return fields with URIs, and declares 'ONE parallel call'. 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 highly informative, with example queries front-loaded. Every sentence adds value given the tool's complexity. Could be slightly more concise, but the structure is logical and aids understanding.

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 thoroughly explains what is returned (cik, recent_filings with URIs, fundamentals sorted, patents status, news, LEI). It also covers limitations (patents soft-fail) and input constraints (names not supported). This is complete for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying that names are not supported (only ticker or CIK), providing examples like 'AAPL' and '0000320193', and explaining that the type enum currently only supports 'company'. This goes beyond the schema's basic 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' and distinguishes it from siblings like resolve_entity by explicitly saying 'names not supported — use resolve_entity first'. It also says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', directly differentiating from other tools.

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

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

Explicitly says when to use (holistic view requests) and when not (if only have a name, use resolve_entity). Also provides explicit alternatives like 'use resolve_entity first' for name resolution, and implies not to use for single-pack lookups.

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

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

Annotations already declare readOnly and idempotent hints. The description adds 'Keyless, offline', reinforcing no external side effects. It does not contradict annotations and provides useful behavioral context beyond the structured data.

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

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

Three sentences, no filler. Front-loaded with purpose, then format details, then constraints. 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?

For a simple string escaping tool with no output schema and full annotation coverage, the description covers purpose, formats, and offline behavior completely. 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?

While schema descriptions exist with 100% coverage, the description enriches parameter understanding by detailing the format values with examples (e.g., \uXXXX for js, &#xNN; for html). This goes beyond the schema's simple list.

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 'Escape a string' and lists four distinct escape formats (js, html, url, all-nonascii). It distinguishes from sibling 'unescape_string' by its opposite function. The additional 'Keyless, offline' clarifies 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?

Description explicitly names the formats and indicates no external dependencies ('Keyless, offline'). It does not explicitly mention when not to use or reference alternatives like 'unescape_string', but the context is clear enough for selecting the correct 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 destructiveHint=true and idempotentHint=true, which the description ('Delete') aligns with. No contradictions. The description adds context about clearing sensitive data, but much of the behavioral insight is already in 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 that are front-loaded with the core action and directly followed by usage guidance. No extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool does, when to use it, and how it relates to sibling tools. No gaps.

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

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

Schema coverage is 100% with one parameter key described as 'Memory key to delete'. The description does not add additional semantics beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the verb 'delete' and the resource 'previously stored memory by key'. It also explicitly names siblings 'remember' and 'recall', distinguishing this tool's function.

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

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

Provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool over 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=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt.' This provides context beyond annotations, though it could mention potential rate limits or page size constraints.

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

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

The description is three sentences long with no filler. The first sentence front-loads the purpose, the second describes the extraction process, and the third lists use cases. Every sentence adds value, making it concise and 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?

For a tool with only two parameters and no output schema, the description fully covers what the tool does, how it works, and what the output is. It mentions the output format (llms.txt markdown) and deployment location, which is sufficient for understanding without needing further details. Use cases are also provided.

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

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

Schema description coverage is 100%, so the input schema already documents both parameters (url and max_links) with descriptions. The description adds no new semantic information about the parameters beyond the context 'for any URL' and 'Maximum number of link entries,' which is already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt creation, which is unique among the listed 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 use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It offers clear context for when to use this tool but does not explicitly state when not to use it or contrast with alternatives, which prevents a score of 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds scoping (caller's subscriptions) and return field details, enhancing transparency 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, front-loaded with the main action, no redundant information.

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

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

Despite no output schema, the description lists returned fields, and the parameter is fully described in the schema. Adequate completeness for a simple list 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 the description does not add extra meaning to the parameter beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields, effectively distinguishing 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?

Explicitly advises using the tool to review subscriptions before adding more or to find an ID for cancellation, providing clear when-to-use guidance.

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

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

Annotations only declare non-readOnly, non-idempotent, etc. The description adds valuable behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. It doesn't disclose what happens after submission (e.g., confirmation), but the added constraints are sufficient.

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, then detailed usage, then constraints. Each sentence serves a purpose, no fluff. It's concise yet comprehensive, using a clear structure that aids quick understanding.

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 3 parameters (2 required), nested object, and no output schema, the description covers: all use cases, parameter guidance, rate limiting, and quota info. It doesn't explain return values (acceptable without output schema), but it could slightly improve by noting that confirmation is provided upon successful submission.

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

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

Input schema has 100% coverage, but the description adds value: clarifies the 'type' enum meanings beyond the schema description, specifies 'message' max length (2000 chars), and explains the 'context' object's role (optional structured context). This supplements the schema well.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature, data_gap, praise) which distinguish it from sibling tools like 'ask_pipeworx' or '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?

Excellent usage guidance: explicitly describes when to use each feedback type ('Use when a tool returns wrong/stale data...'), provides an explicit exclusion ('don't paste the end-user's prompt'), and advises on describing issues in terms of Pipeworx tools/packs.

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 value beyond annotations by explaining the tool is a self-aggregating signal from CF analytics-engine, involves no PII, and is cached 5min-1h. This contextual behavior is useful beyond the read-only and idempotent hints.

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, each earning its place. It is front-loaded with the main function, followed by use cases and additional context. 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?

The description explains what the tool returns (top tools, top packs, total call volume) and mentions caching behavior. For a simple read-only tool with no output schema, this is complete and sufficient.

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

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

The schema already covers the parameter with enum and description (100% coverage). The description adds extra meaning by explaining the use cases for different windows (short vs long), providing helpful context 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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resource, and distinguishes itself from siblings like 'discover_tools' by focusing on trending data.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't specify when not to use it or directly name alternatives, the context is still clear enough for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, safe. Description adds rich behavioral details: fill check logic, semantic anchor requirements, partition filter, response structure. No contradictions with annotations.

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

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

Description is dense and informative but somewhat lengthy. However, it is well-organized with clear sections and front-loaded with the core purpose. Every sentence adds value, and the length is justified by the tool's complexity.

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

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

Despite no output schema, the description thoroughly documents the response structure (opportunities array, partition_check object, fill check details). Covers edge cases, filters, and trade recommendations. Complete for a complex tool.

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

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

Schema has 100% coverage with descriptions for both parameters. Description significantly adds meaning: explains the difference between event and topic, what values to pass (slugs vs. questions), and how each mode works. Goes well 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event) and contrasts with sibling tools like polymarket_fill_risk. Purpose is specific and actionable.

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 when to call with no args (trending scan), when to use event mode (specific market slug), and when to use topic mode (cross-event scanning). It also warns against trading when realizable_edge_pp ≤ 0 and points to polymarket_fill_risk for custom sizing. Provides clear context 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 significant behavioral context: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the response structure with by_segment and diagnostics, caching behavior (Cached 1h at KV level), and edge calculation details. This goes well beyond the annotation baseline.

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 verbose, spanning multiple paragraphs with highly technical details. While structured into sections (model families, response, knobs, diagnostics), it could be more concise. Some sentences are long and dense, which may reduce readability for an AI agent.

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 covers the return structure (by_segment segments), diagnostics, filters, edge computation, caching, and knobs. The lack of an output schema is compensated by extensive description of fields and segments.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the 'Tradeable-Edge Knobs' section and providing practical guidance (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model' for slippage_pp). It also explains how min_partition_leg_kelly interacts with other filters.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It provides a specific verb (scan, return), resource (Polymarket markets), and scope (Pipeworx vs market price). The use case 'what should I bet on today' distinguishes it implicitly from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description includes explicit usage guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs and filtering options, helping agents decide when to apply filters. However, it does not explicitly state when NOT to use this tool or directly compare to 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?

Adds extensive behavioral context beyond annotations: describes output structure (tracked[], expired[], snapshot_dates[]), explains fields like trend and decay_pp_per_day, and notes that snapshots are written on cache-miss. No contradiction with annotations (readOnlyHint=true, 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?

Well-structured with purpose, args, response fields, and limits. Slightly wordy but every sentence adds information; front-loaded with core question. Could be trimmed but 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?

No output schema, but description fully explains return values (tracked[], expired[], snapshot_dates[]) and limitations. Covers all necessary information for an AI agent to understand what the tool returns and how to interpret it.

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

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

Schema coverage is 100% and description adds meaning: clarifies default values (days=14, window='1wk'), explains the clamp range (2-30), and context about what each parameter controls (lookback, snapshot family). Adds value beyond the schema.

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

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

The description explicitly states the tool's purpose: edge persistence and decay telemetry. It answers a clear question about how long an edge has existed and whether it is shrinking. This distinguishes it from the sibling `polymarket_edges`, which likely provides 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 a concrete example of when to use the tool (differentiating fresh vs old edges) and mentions limits (60-day TTL, daily closes). Lacks explicit when-not-to-use or alternative tool comparisons but gives sufficient context for appropriate use.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) are consistent with the description, which adds behavioral details like walking the ladder, returning verdicts, and listing thin legs. No contradictions; the description enriches transparency beyond annotations.

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

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

The description is well-structured, front-loading the core concept, then detailing modes and return fields. It is somewhat long (180+ words) but every sentence adds value; a minor trim could improve conciseness without losing information.

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

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

Despite lacking an output schema, the description lists all critical return fields (top_of_book, vwap_fill_price, slippage_pp, captures, thin_legs, etc.) and explains the risk of directional bias. It fully covers the tool's behavior for both modes.

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: explains mode-specific interpretation of size_usd, default side for basket (auto from partition sum), and clarifies that size_usd is max spend on buys or target proceeds on sells. The description is essential for correct parameter usage.

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 checks realizable vs theoretical edge against live CLOB order-book depth, with two distinct modes (single-market and basket). It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges, telling the agent to use this tool before acting on those signals.

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

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

Provides explicit guidance on when to use this tool: before executing polymarket_arbitrage or polymarket_edges trades above ~$500. Warns about partial basket fills converting arbs into unhedged directional positions. No ambiguity about usage context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond these by explaining the spread calculation, the two compatibility_warning cases (non-equivalent bet shapes and semantically unrelated events), temporal alignment checks, and the meaning of skipped 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?

The description is relatively long but well-structured with clear section headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence contributes useful information. Minor verbosity in explaining skipped counters could be tightened, but overall 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's complexity (cross-venue comparison, multiple parameters, safety fields, no output schema), the description is complete. It explains the output structure (leg-by-leg prices, top_spreads_pp), the compatibility_warning and temporal_alignment fields, and how skipped counters work. An agent has enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds significant meaning: it explains the relationship between parameters (topic vs explicit overrides), lists the exact topic strings, and describes how parameters interact (e.g., kalshi_event_ticker overrides the topic-mapped side). This enriches the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by specifying the two venues and the concept of equivalent bet shapes. It also outlines two modes (topic shortcuts and explicit event identifiers), providing a specific verb+resource+scope.

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

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

The description explicitly explains when to use each mode: topic shortcuts for pre-mapped macros (like 'fed', 'btc') and explicit tickers for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning, so the tool should not be assumed tradeable. This provides clear context for when-not-to-use and sets expectations.

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 and idempotentHint, and description aligns as a retrieval operation. Adds context about scoping and pairing, which is useful beyond annotation hints.

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

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

Three sentences, front-loaded with action, then use cases and scoping. No wasted words; every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and paired tools. No gaps in 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 coverage is 100% and describes the key parameter. Description clarifies the behavior when omitted (list all keys), which adds slight meaning beyond 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 retrieves a value by key or lists keys if omitted, with specific verb+resource and use cases like lookup of stored context. It distinguishes from siblings '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?

Explicitly explains when to use (look up stored context) and when to omit the key (list keys). References alternatives: 'remember' to save, 'forget' to delete. Also notes scoping by 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?

The description aligns with annotations (readOnlyHint, idempotentHint) by stating 'Pull... events' and 'Polls work fine.' It adds critical behavioral details beyond annotations: the mark_read parameter flags events as read, affecting future calls. It also clarifies the feed's behavior and the raw event payload, enhancing predictability.

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

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

The description is a single dense paragraph that covers purpose, parameters, return fields, and alternatives without excess. It front-loads the main action and is well-organized, though a bulleted structure could improve readability. Every sentence adds value, and no unnecessary details are present.

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 return data (source, citation_uri, raw event payload). It covers the mark_read behavior and filter options, making the tool self-contained for most use cases. Minor omission: does not explicitly state the response is an array, but it's implied by 'most recent alerts.'

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

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

The input schema has 100% coverage with descriptions for all 5 parameters. The description reinforces these by providing examples (e.g., type 'sec_8k') and explaining the effect of mark_read and unread_only. This adds meaning beyond the schema, especially for new users, though the schema alone is already clear.

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 'Pull fired events from your subscription feed,' clearly stating the tool's action and resource. It distinguishes itself from sibling tools by focusing on alert feed retrieval, and specifies key return fields (source, citation_uri, payload), leaving no ambiguity about what the tool does.

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

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

The description explains when to use the tool (pulling alerts), provides filtering options (type, since), and mentions that polling is fine. It also offers an alternative: the same feed is available via direct API for scripts/dashboards, giving clear usage context. However, it lacks explicit 'when not to use' guidance relative to siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds detailed behavioral context: fans out to three sources in one parallel call, preferred source fallback, soft-failure handling, return structure (grouped changes, total count, URIs). 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 well-structured single paragraph. Front-loaded with example queries, then explains function, sources, parameters, and return format. 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?

Despite no output schema, the description adequately covers return format (changes grouped by source, total_changes, citation URIs). It explains fallback logic, soft-fail for USPTO, and alternative tool (entity_profile). All relevant behavioral aspects are covered for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples for 'since' (e.g., '7d', '30d', '1y') and noting typical usage ('30d' or '1m'). It also clarifies that 'type' is limited to 'company' and explains 'value' can be ticker or CIK, which is beyond schema, but not critically different.

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 provides a change feed for a company within a time window, aggregating multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling entity_profile by specifying when to use the latter for static profiles. The verb and resource are specific, and the description answers common user queries.

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 gives example queries and explains when to use this tool vs. entity_profile. Includes fallback behavior (GDELT to GNews) and soft-fail for USPTO. Provides parameter format guidance for 'since' (ISO date or relative shorthand) with typical values.

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

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

The description provides significant behavioral details beyond the annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This adds context about scope and persistence that annotations do not cover. No contradiction with annotations.

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

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

The description is concise with five sentences, each adding value. It front-loads the purpose, then provides usage guidance, then behavioral details, and ends with sibling references. 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 the tool's simplicity (2 required string params, no output schema), the description covers all needed context: purpose, when to use, how it works (scoping, persistence), and relationships with siblings. 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?

The input schema has 100% description coverage for both parameters. The description adds examples and context (e.g., 'key' examples like 'subject_property' and 'value' description 'any text'). Since schema already documents them well, the description adds moderate extra value, justifying a score above baseline.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and the resource 'key-value pair'. It distinguishes itself from siblings by mentioning pairing with 'recall' and 'forget', making it clear that this is the write operation.

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: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget for retrieval and deletion. However, it does not explicitly state when not to use this tool, which prevents a perfect score.

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 safe read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it cascades through multiple lookup endpoints, replaces 2-3 manual lookups, and specifies output details (ticker, CIK, RxCUI, citation URIs). 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 fairly concise given the complexity, and it front-loads with examples and usage context. Each sentence provides useful information, though the list of supported types could be slightly more streamlined.

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

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

For a tool with two simple parameters and clear behavior, the description is complete. It explains what is returned for each entity type, includes citation URIs, and covers input variations. No output schema exists, but the description adequately covers return 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 100% with both parameters described. The description adds value by explaining that 'value' accepts multiple formats (ticker, CIK, or name for company; brand or generic name for drug) and mentions auto-disambiguation, going beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: resolving a name to a canonical/official identifier. It provides specific examples ('What's the ticker for...'), lists supported entity types, and distinguishes itself from sibling tools like 'compare_entities' and 'entity_profile' by focusing on ID lookup.

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,' giving clear usage context. It details supported types and the forms of input accepted. While it doesn't explicitly state when not to use, the strong directive 'first' sufficiently guides the agent.

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

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

Description explains internal behavior: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized. This adds context beyond the already rich annotations (readOnlyHint, idempotentHint, etc.), such as the multi-call orchestration and ranking logic. 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?

Three concise sentences with no fluff. First sentence states purpose, second explains process, third gives usage example. Every sentence adds value. Well front-loaded with the core action.

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 tool complexity (4 params, no output schema), description is complete. It covers purpose, input parameters with usage nuances, internal process (probing and ranking), and return format (ranked list with score, confidence, signal density). 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% (all 4 parameters described in schema). Description adds meaning beyond schema: e.g., 'First entry treated as the subject for narrative', which models default, and that _apiKey is required only when 'anthropic' in models. This clarifies parameter usage and relationship.

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 states exactly what the tool does: compares AI visibility across multiple entities side-by-side, using specific verb 'Compare' and resource 'AI visibility'. It clearly distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison) by specifying its multi-entity probing and ranking 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?

Description explicitly says 'Useful for competitive AI-marketing audits' and provides an example question. It references sibling tool ai_visibility_check as the underlying probe, helping agent understand the tool's role. However, it does not explicitly state when not to use it or fully list 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 indicate read-only, idempotent, and non-destructive behavior. The description adds significant detail beyond annotations: explains fan-out across two services, graceful degradation on partial failures, specific timeout for bundlephobia's first measurement, and exactly what fields are returned (summary block, advisories, links, alternative versions). 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 well-structured, front-loading the core purpose in the first sentence. It contains about 5-6 sentences, each providing necessary detail (scope, use cases, alternatives, failure behavior, return structure). Could be slightly more concise, but no extraneous 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 lacking an output schema, the description fully details the return structure (summary block fields listed, per-advisory detail, links, recent alternative versions). It also covers failure modes, ecosystem limitations, and version defaults. The tool has moderate complexity, and the description leaves no critical 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% for both parameters. The description adds valuable context: notes that scoped packages (e.g., '@types/node') are accepted, and explains the default behavior when version is omitted (latest published version). 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 explicitly states the tool's purpose: a composite check for adding npm packages, covering deps.dev and bundlephobia. It clearly differentiates from siblings by specifying 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' The verb 'scan' and resource 'dependency' are clearly defined.

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

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

Provides explicit when-to-use instructions: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me."' It also covers when-not through ecosystem limitations, alternative tools for non-NPM, and behavior on partial failures, including timeout expectations (5-30s for new versions).

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) the description adds critical detail: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This greatly aids the agent in understanding behavior.

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

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

The description is detailed yet efficient, front-loading the purpose and use case. Every sentence adds value, though slightly more structure (e.g., separating usage from technical details) could improve scannability.

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 thoroughly explains what is returned (top-N passages with character offsets and similarity scores) and covers edge cases (truncation flag). It leaves no major gaps for a tool of this complexity.

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

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

Schema covers all parameters at 100%. Description reinforces the cap for 'text' and gives example queries for 'query', but does not add significant new meaning beyond what the schema 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?

The description clearly states 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article). It distinguishes itself from siblings by pairing with ask_pipeworx_grounded and framing the use case against the gateway 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how search_within saves context. It also describes the pairing pattern with ask_pipeworx_grounded. 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 are minimal, but the description adds rich behavioral traits: delivery channels, SMS 10/day cap, phone verification, webhook signing and auto-disable. 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?

Front-loaded with purpose and return value, then requirements, types, delivery. It is comprehensive but a bit lengthy; could be slightly more concise without losing key 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 (3 params with nested objects, no output schema), the description is complete: covers all types, delivery channels, constraints, and account requirements. Return format is simple (subscription id), so no need for more.

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, but the description adds extensive context: explains each enum type with examples, sub-parameters for params, and delivery details. This goes well 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource, and it distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 includes when to use (creating subscriptions) and requirements (Pipeworx OAuth account). It lists types and delivery options, but lacks explicit 'when to use this vs alternatives' statement, though siblings are clearly different.

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, etc. The description adds significant behavioral context: it returns structured example questions, can be focused by topic, and describes the output shape. 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 packs much information into a compact structure: common queries, output details, usage variants, and sequential guidance. Every sentence contributes meaning.

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

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

Given no output schema, the description adequately explains the return format (category-bucketed questions with tool+arg shape). The one optional parameter and simple behavior are fully 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?

Only one parameter with 100% schema coverage. Description adds usage nuance: 'omit for full spread' and re-lists options, providing context beyond the schema's property 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 is the onboarding entry point, returning category-bucketed example questions with tool+argument shape. It lists many specific categories and distinguishes itself from siblings by being the first stop 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 to call FIRST when not yet familiar with Pipeworx, and to call with no args or a topic. Mentions meta-tools as context but doesn't contrast directly with siblings like ask_pipeworx or discover_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, openWorldHint, idempotentHint, and non-destructive. The description adds 'Keyless, offline' but provides limited new behavioral context 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 a single, focused sentence that efficiently conveys the tool's purpose, supported escape types, and key properties (keyless, offline) without any waste.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It clearly specifies input format and behavior, aided by rich annotations.

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

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

Schema coverage is 100% with the single parameter 'text' described. The description does not elaborate on the parameter beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action: unescape strings with specific escape patterns (\uXXXX, \xNN, etc.). It distinguishes from sibling 'escape_string' by being the inverse operation.

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

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

The description mentions 'Keyless, offline,' indicating no authentication or network needed, making it safe to use anytime. However, it does not explicitly state when to use vs alternatives or when not to use.

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

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

Annotations already provide idempotentHint and destructiveHint. The description adds valuable behavioral context: the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. 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?

Two sentences with no redundancy. The action is front-loaded, and every clause adds necessary information (ownership, deactivation, historical availability).

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 essential aspects: what it does, constraints, side effects, and relation to other tools. Complete and self-contained.

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 parameter is well-documented. The description adds cross-reference by stating 'returned by subscribe', which 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 action ('Cancel a subscription by id') and the resource (subscription). It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying the operation type.

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. However, it does not explicitly state when not to use or suggest alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it returns a verdict, structured form, actual value with citation, and percent delta, and explains it replaces multiple sequential calls. This goes well 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 relatively long but well-structured: it leads with the core purpose in quotes, then usage guidance, then technical details and scope. Every sentence adds value, though it 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 the tool has one parameter and no output schema, the description adequately explains the return format (verdict, structured form, citation, delta). It notes the v1 scope limitation. It is complete enough for an agent to use correctly, though edge cases or full output details are not exhaustive.

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 only one parameter (claim) and 100% schema description coverage, the schema already defines the parameter well. The description adds examples and clarifies the natural-language nature, but does not add substantial new meaning beyond the schema's description. 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 validates natural-language claims against authoritative sources, with specific examples like 'Is it true that...' and 'fact check'. It distinguishes its function from siblings by describing it as replacing 4-6 sequential calls, though not explicitly naming alternative tools for non-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.' It also notes the v1 scope is company-financial claims, implying when not to use it. However, it does not mention alternative tools for other claim types, leaving some gap in guidance.

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