Textcase

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

Annotations already declare read-only and idempotent behavior. The description adds value by disclosing default model, API key requirements, and cost implications (free for Workers AI, pay-as-you-go for Anthropic), which goes 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 three well-structured sentences with no wasted words. It front-loads the core purpose and efficiently covers usage, parameters, and return structure.

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

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

Despite lacking an output schema, the description fully specifies the return format (per-model {score, confidence, signals, raw_response} + combined view) and provides sufficient context for all critical aspects of tool usage.

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

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

With 100% schema coverage, the description still adds meaning: it explains the default model for the 'models' parameter, the requirement and role of '_apiKey', and the purpose of 'context' for disambiguation. This enriches the schema's built-in descriptions.

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

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

The description clearly states the tool probes LLMs about an entity and scores visibility, using specific verbs and resources. It differentiates from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring and return structure.

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 identifies explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and notes prerequisites for Anthropic probing. However, it lacks explicit exclusion of 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?

Adds context beyond annotations by describing output format ('keyed by name') and indicating all cases are returned. Annotations already cover idempotency, read-only, and non-destructive nature.

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

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

Single sentence, 12 words, front-loaded with verb, 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?

Given the tool's simplicity (1 param, full annotations, no output schema), the description adequately covers input, operation, and output format.

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

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

Schema fully covers the single parameter 'text' with description. Description does not add new parameter-specific information, so baseline 3 is appropriate.

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

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

Description clearly states verb 'Convert' and resource 'text', specifies output is 'ALL supported cases' returned 'keyed by name', distinguishing from sibling 'convert_case' which likely converts to a single case.

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

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

Implies batch usage with 'at once', but no explicit guidelines on when to use this tool versus alternatives like convert_case. An agent can infer from context, but not explicitly stated.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: it routes to 4,552 tools across 1,160 sources, returns structured answers with stable pipeworx:// citation URIs, and is a 'one fast call'. This extra information is helpful but not essential given 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 longer but front-loaded with key guidance ('PREFER OVER WEB SEARCH') and includes examples and sibling differentiation. 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's complexity (router to thousands of sources), the description covers scope, output format, use cases, and alternatives. It does not mention limitations or error handling, but for a high-level tool this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema provides for the 'question' parameter and its aliases. The examples in the description help illustrate usage but do not elaborate on parameter constraints or formats.

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

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

The description clearly states the tool's purpose: it routes factual questions to a large set of verified sources and returns structured answers with citations. It provides extensive examples of domains and question types, and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly states when to use this tool (for factual questions about real-world entities, events, numbers) and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It advises 'START HERE for most questions' and provides 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?

Adds significant behavioral context beyond annotations: explains the extraction process, return structure with refusal reasons, and the cost implication ('one extra LLM call'). Annotations already declare readOnlyHint and idempotentHint, and the description is consistent with those.

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 and front-loaded with the main purpose, then behavior, then use cases. Every sentence adds value, though it could be slightly more concise (e.g., the list of refusal reasons could be abbreviated). Overall, efficiently conveys key information.

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

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

Given no output schema, the description fully explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists possible refusal reasons. It covers all essential aspects: what it does, when to use, how it differs from sibling, and what to expect back, leaving 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 description coverage is 100%, so baseline is 3. The description simply states 'Your question in natural language' and mentions 'accepts query, q, prompt, text, input as aliases,' but adds no additional semantics beyond what the schema already provides for each aliased parameter.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by explaining the extra extraction step and refusal mechanism. The verb 'extracts answer using ONLY what the tool result contains' is specific and unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, etc.). Also contrasts with 'ask_pipeworx' for casual lookups and mentions cost trade-off, providing clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond by detailing fan-out behavior, low-confidence handling, closed market handling, wide spread warnings, resolution-rule risk, and response shapes. It adds rich context about safety and edge cases, consistent with annotations.

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

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

The description is long but well-structured: starts with a one-sentence summary, then sections for classifiers, fan-out examples, response shapes, safety, etc. It is front-loaded with the key purpose. While some details (e.g., extensive fan-out examples) could be condensed, the length is justified for the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response shape (market, analysis, evidence, resolver contract, parent_event, news fields). It covers inputs, behavior, safety, edge cases, and return structure comprehensively. All three parameters are well-documented. The description leaves little ambiguity for an agent.

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

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

Schema description coverage is 100% with descriptive parameter descriptions. The description adds significant value beyond the schema: for 'market', it explains multiple input formats (slug, URL, question text) with examples; for 'include_raw', it explains size implications; for 'depth', it clarifies options. This enriches the schema's baseline of 3.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). Use cases are explicitly listed ('should I bet on X', etc.), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides extensive guidance on when to use, including use cases, classifier types, fan-out examples, and safety features. It explains when not to trust results (low confidence, closed markets, wide spreads) but does not explicitly contrast with alternative tools like polymarket_edges or validate_claim. The guidance is thorough but lacks explicit when-not comparisons.

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, idempotent, read-only behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and that results are sorted by primary metric. 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?

Four sentences with efficient, front-loaded style. Each sentence adds unique value—example queries, usage preference, data details, return format. No redundant or filler content.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs) and key behaviors (sorted, fiscal year handling). For a 2-parameter tool, all essential context is provided for correct invocation.

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

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

Schema coverage is 100% with enums and descriptions. The description enriches this by explaining what data is pulled for each type (e.g., 'revenue + net income + cash' for companies) and that results are sorted, providing 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 performs side-by-side comparisons of 2–5 companies or drugs, with specific examples ('X vs Y', 'rank these companies'). It differentiates from sibling tools like 'entity_profile' by emphasizing its comparison 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?

Explicitly instructs to prefer this tool over sequential single-entity lookups when comparing entities ('ALWAYS PREFER over sequential single-pack lookups'). Provides clear use cases and hints at alternatives (single 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 readOnlyHint, idempotentHint, etc. The description adds value by noting 'keyless, offline', which informs the agent that no API keys or network access are needed, and does not contradict any annotations.

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

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

The description is a single concise sentence that starts with the verb 'convert' and lists all relevant targets, with no superfluous words.

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

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

For a simple conversion tool with rich annotations (readOnly, idempotent, not destructive), the description covers purpose, parameters, and key behavioral traits (keyless, offline), making it fully adequate for correct invocation.

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

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

Schema coverage is 100%, description lists all valid target cases (which schema does not enumerate) and explains the text parameter, providing context beyond the raw schema field 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 verb 'convert' and the resource 'text', and lists 11 specific target cases (camel, pascal, snake, etc.), fully distinguishing this utility tool from sibling tools that cover other domains.

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

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

The description explains the tool's purpose for converting text to various cases, and the 'keyless, offline' note implies it has no external dependencies, but does not explicitly compare to alternative tools or state when not to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds latency expectation (15-60s), account requirement, paid plan, result structure (evidence with citations and gaps), and data source scope. No contradictions.

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

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

Description is long but well-structured: front-loaded with critical prerequisites (account), then usage guidelines, then core functionality. Every sentence adds value, though slight reduction possible without loss.

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

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

Given no output schema, description fully explains return format (findings packet with evidence, confidence, source, citations, gaps). Parameters are covered, sibling tools listed, and complexity of tool is addressed. Complete for agent use.

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

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

Schema coverage is 100%. Description enriches by explaining depth values (quick=3, standard=5, thorough=8) and that thorough requires payment. For question, it clarifies natural language and suitability for 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's purpose: grounded multi-source research over structured data, decomposing questions into facets. It distinguishes from siblings by explicitly mentioning ask_pipeworx for single lookups and news topics, and warns about not being open-web search.

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 and when-not-to-use: account required, alternatives for unsigned users (ask_pipeworx), single lookups, and breaking news. Also mentions depth level requirements ('thorough' needs paid plan).

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

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

The description adds behavioral details beyond annotations: it returns top-N relevant tools with full input schemas and curated examples, and each result is ready to call directly. This complements the readOnly and idempotent hints from annotations. No contradiction detected.

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 slightly verbose. It is front-loaded with the core purpose and usage instructions. Every sentence adds value, but some redundancy (e.g., listing domains) could be trimmed without loss.

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

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

Despite lacking an output schema, the description explains what is returned (top-N tools with names, descriptions, schemas, examples) and how to use it. For a discovery tool with 6 parameters and clear semantics, it is complete.

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

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

The schema covers all 6 parameters with descriptions, achieving 100% coverage. The description adds value by explaining that the query parameter accepts natural language and lists common domains (SEC filings, FDA drugs, etc.), and notes aliases. However, the schema already provides the core meaning.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies a verb (find/discover) and a resource (tools), and distinguishes itself from sibling tools by being a general discovery tool rather than a specific data accessor.

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 need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on usage context and priorities.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), mentions USPTO PatentsView API sunset and soft-failure, and details the return fields (cik, filings with URIs, fundamentals, patents, news). 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 a single paragraph but well-structured with examples upfront, then detailed explanation. It is front-loaded and every sentence adds value. Could be slightly more structured, but remains concise and informative.

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

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

Despite having no output schema, the description thoroughly explains the return structure (cik, company_name, recent_filings with URI formatting, fundamentals sorted by period_end, patents, news via GDELT→GNews fallback, LEI). This fully covers the complexity of a multi-source profile tool.

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

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

Schema coverage is 100% with descriptions, but the tool description adds meaning beyond: it specifies value accepts ticker or zero-padded CIK (with examples), and notes names are not supported. It also explains type is limited to 'company' for now.

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 user-like queries ('Tell me about X', 'research Acme') and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb (profile), resource (US public company), and distinguishes from sibling tools like resolve_entity.

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

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

It advises 'ALWAYS PREFER over chaining single-pack...when user asks for a holistic view' and explicitly says 'names not supported (use resolve_entity first if you only have a name).' This provides clear when-to-use and when-not-to guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds minimal behavioral context beyond stating deletion; does not clarify idempotent behavior or missing key handling.

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

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

Two concise sentences with front-loaded action, 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 simplicity of the tool (1 param, no output schema) and presence of annotations, the description provides sufficient context for correct invocation.

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

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

Schema description coverage is 100% and description does not add additional meaning beyond the schema's description of the 'key' property.

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

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

Description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. Distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with siblings.

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

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

The description explains the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output format. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral context without contradiction.

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

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

The description is two sentences with clear purpose and process, plus a bullet-like list of use cases. It is concise and front-loaded, though the use cases could be more structured. Each 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 tool with no output schema, the description covers input, process, output format ('single text blob ready to drop at site-root/llms.txt'), and use cases. Combined with annotations, the context is fully sufficient.

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

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

Schema description coverage is 100%; both parameters 'url' and 'max_links' have schema descriptions. The tool description does not add additional parameter 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 it generates a 'llms.txt' file for any URL, specifying the verb 'Generate' and resource 'llms.txt'. It distinguishes from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on producing the standard markdown format.

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 lists 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 does not directly compare to alternatives but provides clear context for when to use the 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it lists 'the caller's' subscriptions, implying personal scope, and enumerates return fields. 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?

Two sentences, front-loaded with the core action and return fields, followed by usage guidance. 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?

While there is no output schema, the description lists the return fields, compensating adequately. The tool is simple (one optional parameter), and the description covers its purpose and usage well.

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 parameter include_inactive is described in the schema; the description does not add further semantics about it. The description mentions return fields but not parameters.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.). It distinguishes from siblings like subscribe and unsubscribe which are for adding or removing subscriptions.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides when to use it, though it does not mention when not to use it or explicitly name sibling 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?

Beyond annotations (which are false for readOnly, destructive, etc.), the description discloses rate limits (5 per identifier per day), that it is free, and does not count against tool-call quota, adding valuable behavioral context.

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

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

The description is concise with a clear front-loaded purpose, followed by usage guidelines and constraints. Every sentence adds value and there is no redundancy.

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

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

Given no output schema, the description adequately explains return handling (digests, roadmap) and provides all necessary context for an agent to use this tool correctly, including what not to do and rate limits.

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

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

Schema coverage is 100% with parameter descriptions already present. The description restates some enum values and adds context about not pasting end-user prompts, but does not significantly extend beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific categories (bug, feature, data_gap, praise, other) which distinguishes it from sibling tools that perform other functions.

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

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

Explicitly tells when to use the tool for each feedback type and provides exclusions like 'don't paste the end-user's prompt.' It also mentions rate limits and quota implications, giving clear usage context.

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

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

Adds value beyond annotations by disclosing aggregation source (CF analytics-engine), no PII, and caching policy (5min-1h). No contradiction with annotations.

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

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

Three concise sentences with bullet points. Front-loaded with core purpose, 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?

Fully covers input semantics, output contents, caching, source, and privacy. No output schema needed as description is complete.

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

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

Schema covers the only parameter fully, but description adds guidance on choosing window length (hot vs. steady-state). Exceeds baseline 3.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window, distinguishing it from sibling tools that focus on querying or other functions.

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 three explicit use cases (discovering hot data, confirming canonical tool, aligning use case). Lacks explicit when-not-to-use, but context is sufficient given no obvious 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 safe, read-only, idempotent behavior. The description adds substantial context: monotonicity checks, partition verification, semantic similarity filters, placeholder filtering, and fill-rate analysis. 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?

Long but well-structured with clear sections for each mode and behavior. Every sentence adds value, though some detail (e.g., fill check mechanics) 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?

No output schema, but the description thoroughly covers response fields, edge cases (low similarity, placeholder filtering), and trade feasibility via fill check. Comprehensive for a complex arbitrage tool.

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

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

Schema coverage is 100%, and the description enriches both parameters with format examples, mode explanations, and behavioral nuances (e.g., topic uses Jaccard similarity, event walks child markets).

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and specifies when to use each, providing concrete examples.

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

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

Explicit guidelines for when to use no args (trending scan), event (specific market), or topic (cross-event scanning). Includes when not to trade (fill check) and alternates like polymarket_fill_risk.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: 1-hour KV caching, detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation net of slippage, 24h move warnings, and diagnostics for empty segments. No contradictions with annotations.

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

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

The description is very long and dense, covering many details. While every sentence adds value, the length reduces overall conciseness. The structure uses clear sections (model families, knobs, response format) but could be more streamlined without losing critical 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 thoroughly explains the response structure (by_segment segments, top-level fields like fed_candidates, _diagnostics), caching behavior, and all knob effects. For a complex tool with 9 parameters and no output schema, the description provides comprehensive coverage of all behavioral and output 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% with good descriptions, so baseline is 3. The description adds extra meaning beyond the schema, such as explaining when to adjust slippage_pp (zero fees but thin depth) and the rationale behind min_partition_leg_kelly for partition arbs. This pushes the 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 precisely states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx's proprietary models and 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?

The description is explicitly built for discovering daily betting opportunities and includes detailed guidance on knobs and filters (e.g., min_liquidity, max_spread_pp). It notes that Fed bets are excluded from ranking. However, it does not explicitly state when to use alternatives like polymarket_arbitrage or provide when-not-to-use scenarios, 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 already declare readOnlyHint, openWorldHint, idempotentHint. Description adds rich detail: response structure (tracked, expired, snapshot_dates), decay computation, and limitations (60-day TTL, snapshot start). No contradiction.

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

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

Description is well-structured with clear sections (purpose, args, response, limits). Each sentence adds value and there is no redundancy or fluff.

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

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

Given no output schema, description thoroughly explains response (tracked, expired, snapshot_dates) and covers all parameters and limitations. Complete for a tool with 2 optional parameters.

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

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

Schema coverage is 100% with clear descriptions. Description adds value by specifying defaults, clamp ranges, and meaning of 'window' as snapshot family, which goes beyond 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?

Description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge duration and trend. It distinguishes itself from the sibling 'polymarket_edges' by focusing on time-series and decay.

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

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

Describes when to use (to differentiate fresh vs old edges) and includes explicit limits (history depth, decay from daily closes). Could more explicitly contrast with alternatives but context is clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds rich behavioral details: it walks the order book ladder, checks depth, returns verdict and slippage, and warns about directional risk from partial basket fills. No contradictions with annotations.

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

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

The description is verbose but well-structured with clear sections for modes, return fields, and usage notes. It front-loads the core purpose and uses capitalization for emphasis. Could be slightly trimmed 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?

Given no output schema, the description thoroughly lists return fields for both modes, explains interpretations, and ties usage to sibling tools. It covers all essential aspects for an agent to understand and 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 descriptions cover all 4 parameters, but the description adds contextual meaning: default behavior for side (auto in basket mode), size_usd semantics (spend vs target proceeds), and mode selection via market vs event. Adds value beyond schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it before acting on their 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 usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the mode selection and default behaviors, giving clear context for when and 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?

Goes beyond readOnlyHint/ destructiveHint annotations by detailing compatibility warning logic, temporal alignment, skipped leg counters, and conditions when spreads are meaningless.

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 clear sections, but somewhat lengthy; every sentence adds value though could be tightened.

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

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

Thoroughly explains response fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) despite no output schema.

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

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

Schema coverage is 100% so baseline 3; description adds meaning with allowed topic values, mode differentiation, and override behavior.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage.

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

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

Explains two modes (topic shortcuts and explicit pairing), provides examples, and explicitly warns that most pre-mapped topics may not be tradeable due to incompatibility.

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 and idempotent. The description adds valuable behavioral details: scoping to user identifier, listing all keys if omitted, and pairing with save/delete tools.

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

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

Two efficient sentences plus a closing sentence on scoping and pairing. No fluff, front-loaded with key information.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, parameter behavior, usage guidance, and relationships to sibling tools.

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 schema already describes the parameter. The description adds that omitting the key lists all keys, providing extra clarity 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 specifies the verb 'retrieve' and the resource 'value previously saved via remember' or 'list all saved keys'. It clearly distinguishes from the sibling tools '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?

States when to use: to look up context stored earlier without re-deriving it. Mentions scoping and pairing with remember/forget, giving clear usage 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?

The description contradicts the annotations which declare readOnlyHint=true. The description explains that setting mark_read:true flags events as read, modifying state. This is a behavioral trait that conflicts with the read-only hint. For this contradiction, the score is 1 per guidelines.

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 at around five sentences, with the purpose stated in the first sentence. Every sentence adds meaningful information (return fields, filtering, mark_read, polling, alternative access). No redundant or verbose phrases 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?

For a tool with 5 parameters, no output schema, and no nested objects, the description covers the main purpose, return fields, filter options, and mark_read behavior. It also mentions alternative access. It does not explicitly mention the 'unread_only' parameter or the 'limit' parameter, but these are documented in the schema. Minor gaps, but overall complete enough given the schema coverage.

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 parameter schema has 100% coverage, but the description adds significant value by providing examples (e.g., type 'sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the effect of mark_read. This goes beyond the schema descriptions and aids correct invocation.

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

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

The description clearly states it pulls fired events from a subscription feed, specifying the resource (alerts/events), verb (pull), and key return fields. It differentiates from sibling tools like list_subscriptions by focusing on recent alert events, but does not explicitly exclude other similar 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 explains when to use the tool (to get recent alerts) and provides filtering guidance by type and ISO timestamp. It also explains the mark_read behavior for managing read status and mentions that polling works and an alternative HTTP endpoint exists. However, it does not explicitly state when not to use this tool or list sibling 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?

The description discloses rich behavioral details beyond the annotations: it fans out to three sources in one parallel call, has a GDELT→GNews fallback strategy, and notes that USPTO data soft-fails due to API sunset. This aligns with the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is front-loaded with common use-case examples, then concisely lists the tool's behavior in one sentence per data source. Every sentence adds value, and the structure is logical (purpose, sources, parameter hints, sibling reference). No fluff.

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

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

Given the tool's complexity (multi-source aggregation, fallback, soft-fail), the description is remarkably complete. It explains what each source does, how parameters work, what is returned (structures, counts, citation URIs), and when to use a sibling tool. No gaps remain for an AI agent to correctly select and invoke the tool.

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

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

The input schema already covers all three parameters with descriptions (100% coverage). The description adds extra meaning by providing shorthand examples for 'since' (e.g., '7d', '30d'), a typical usage suggestion ('30d or 1m for monitoring'), and clarification that 'value' accepts ticker or CIK.

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 as a change feed for a company over a time window, listing specific data sources (SEC, GDELT/GNews, USPTO) and distinguishing it from the sibling tool 'entity_profile' which provides static profiles. The verb 'return' and resource 'change feed' are clearly defined.

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

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

The description provides multiple usage examples ('What's new with X', etc.) and explicitly tells when to use the alternative tool 'entity_profile' instead ('Use entity_profile instead when you want the static profile'). It also explains the fallback logic for news sources and the soft-fail for patents.

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

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

Adds context beyond annotations: authenticated users get persistent memory, anonymous sessions 24 hours, key-value scoped by identifier. 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?

Four concise sentences with clear front-loaded purpose, 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?

Fully covers purpose, usage guidelines, behavioral traits, and pairing with siblings for a simple two-parameter tool without output schema.

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

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

Schema coverage is 100% so baseline is 3. Description adds example key formats and clarifies value as 'any text', providing marginal extra value.

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

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

Clearly states the tool saves data for reuse, with specific examples of what to save (ticker, address, preference). Distinguishes from siblings recall and forget by mentioning them.

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

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

Explicitly advises when to use (discover something worth carrying forward) and pairs with recall/forget for retrieval and deletion, though no explicit when-not scenario is given.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that each call cascades through multiple endpoints, and details the exact return values for each type, including citation URIs, providing full behavioral context.

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

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

Description is well-structured with examples and bullet points, but slightly verbose. It remains clear and front-loaded, earning 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 simplicity (two params, no output schema), the description is complete: it specifies inputs, explains return values for both types, and mentions internal cascading. No gaps for an agent.

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

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

Schema coverage is 100%, and description adds significant value: for 'type' it lists exactly the two enum values with their context; for 'value' it gives concrete examples (ticker, CIK, name) and explains auto-disambiguation, enhancing schema info.

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

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

The description clearly states the tool resolves names to official identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes from sibling tools by emphasizing 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides concrete example use cases and mentions it replaces manual lookups, guiding proper usage without ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details: probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized, plus output fields (score, confidence, signal density). No contradictions.

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

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

The description is concise: three sentences that front-load the main action, then detail the method and usage. No superfluous words; every sentence adds value.

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

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

The description covers the tool's purpose, method (probes, ranks), and output structure (ranked list with score, confidence, signal density). While there is no output schema, the description adequately explains the return value. Minor gap: could detail the output format more, but sufficient for a complex tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds semantic value by explaining the first entity is treated as the 'subject' and rest as competitors, and that entities should be 2-8 items. This goes 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 compares AI visibility across multiple entities, uses specific verbs like 'compare' and 'ranks', and distinguishes from the sibling ai_visibility_check by focusing on side-by-side comparison. The example use case reinforces the purpose.

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

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

The description provides clear context for use (competitive AI-marketing audits) with an example question. However, it does not explicitly state when not to use it or directly name alternatives like ai_visibility_check for single-entity checks.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it fans out to two external services, returns a specific summary block with fields, handles partial failures gracefully (sources_failed list), and notes timing caveats. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and usage, then expands on details. Every sentence adds value covering services, use cases, ecosystem boundaries, return format, and error handling. Despite length, it is well-structured and avoids 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?

With no output schema, the description fully explains the return structure (summary block with specific fields, per-advisory detail, links, alternative versions). It also covers error scenarios (partial failures), timing (5-30s for first measurement), and ecosystem scope. The combination of annotations and description leaves no significant 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 clear descriptions for both parameters (package and version). The description adds marginal extra context (e.g., scoped packages are accepted, version defaults to latest), but these are already present in the schema. Therefore, the description does not significantly enhance 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 defines the tool as a composite 'should I add this npm package' check, specifying the data sources (deps.dev and bundlephobia) and the exact information returned. It distinguishes itself from sibling tools by its composite nature and npm-only focus.

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

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

The description explicitly states when to use this tool ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use it (for other ecosystems like PyPI, Maven, etc., which fall under a different tool). It also explains partial failure behavior and the 5-30s timeout for bundlephobia.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds substantial behavioral context: embedding model (BGE-base-en), similarity metric (cosine), overlapping windows, character offsets, char cap with truncation, and return format. 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 moderately lengthy but efficient: front-loaded with purpose, then usage, then technical details. Every sentence adds value, though a minor trim could improve conciseness.

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

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

No output schema exists, but the description fully explains return format (passages with offsets and scores). It covers model details, truncation, and pairing with another tool, making it complete for agent use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples for query, specifying limit range and default, and clarifying text cap. Output details (offsets, scores) help infer parameter utility.

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

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

The description uses a specific verb ('search') and resource ('text inside a fetched record'), clearly stating it performs semantic search on a given text. It distinguishes from siblings like ask_pipeworx_grounded by mentioning pairing, and implies it's not for general search.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context'. Also mentions an alternative tool (ask_pipeworx_grounded) for grounded answering, providing clear 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?

Discloses many behaviors: returns id, OAuth requirement, event types with parameters, delivery channels with limits (sms cap, webhook auto-disable), and idempotent by annotations. 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?

Front-loaded with main action, efficient use of words despite length. Each sentence provides essential detail; no fluff.

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

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

Covers all necessary aspects: types, params, delivery, prerequisites, return value. No output schema needed; description suffices.

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

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

Adds extensive meaning beyond schema: examples for each type, detailed delivery behavior (phone verification, webhook signing), and constraints. Schema coverage is 100% but description enriches understanding.

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

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

Clearly states 'Create a proactive monitoring subscription' with specific verb and resource. Distinguishes from sibling tools 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?

Provides prerequisites (OAuth account), supported types, delivery options, and behavior for each type. Lacks explicit 'when not to use' but context is sufficient for selection.

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

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

Describes behavior beyond annotations: returns category-bucketed example questions with exact tool+argument shape, mentions optional topic parameter and full spread without arguments. No contradictions with annotations (readOnlyHint, 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?

Somewhat long but efficient; front-loaded with common queries, then explains purpose and behavior. Each section adds value, but could be slightly more concise.

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

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

Given no output schema, description explains return type (category-bucketed example questions). For a simple tool with 0 required params, 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?

Schema covers 100% of parameter (topic) with description. The description adds context by listing example values and indicating optionality. Minimal extra beyond schema.

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

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

Clearly states it's the onboarding entry point for understanding Pipeworx capabilities, returning categorized example questions with tool invocation details. Distinct from siblings by being the first-use 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 states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also mentions learning to call meta-tools, providing clear 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?

Adds key details beyond annotations: ownership enforcement, deactivation vs deletion, and historical events remain. No contradiction with annotations which indicate non-destructive, idempotent.

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

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

Two sentences, no fluff, front-loaded with action and immediate key constraint (ownership). Every sentence adds value.

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

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

Given simple tool with 1 param, no output schema, and annotations covering safety profile, description fully covers behavior and effects. Minimal but complete.

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

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

Schema already fully describes the `id` parameter (100% coverage). Description adds 'by id' which is redundant. No additional semantic value beyond schema.

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

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

Clear verb 'cancel' and resource 'subscription', distinguishes from siblings `subscribe` and `list_subscriptions`. Title matches purpose, though includes 'Alerts' which is not in description.

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

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

States ownership enforcement (can only cancel own subscriptions), which guides when to use. No explicit when-not-to-use but context is clear. References `recent_alerts` for historical data.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds significant behavioral context: uses SEC EDGAR + XBRL, returns a verdict with structured form, actual value, citation, and delta, and replaces 4-6 sequential calls. No contradiction.

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

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

The description is fairly long but every sentence adds value. It front-loads with example use cases and clearly explains the tool's capability and output. Could be slightly more concise, but 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 single parameter and no output schema, the description covers purpose, domain, limitations, output format, and even mentions what it replaces. It provides sufficient information for correct invocation, though it might omit edge cases or error handling.

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

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

One parameter 'claim' with schema description coverage 100%. The description reinforces its natural-language nature and provides examples, adding semantic value beyond the schema alone.

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

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

The description clearly specifies the tool's purpose: natural-language claim verification against authoritative sources for company-financial claims. It provides example queries and the output format (verdict, structured form, actual value, citation), and distinguishes from sibling tools by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also narrows the domain to company-financial claims. No explicit when-not-to-use, but the domain limitation is clear.

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