Httpbin

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, confirming safety. The description adds value by detailing that probing uses a default free model, requires a BYO Anthropic key for additional models, and returns per-model results. It lacks details like rate limits or failure modes but aligns with annotations.

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

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

The description is a single paragraph of four sentences, each earning its place: action, default model and optional key, return format, use cases. No redundancy or fluff, front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description thoroughly covers the return values, parameter behavior (cost, optionality), and high-level use cases. It is complete for a tool with 4 parameters, 1 required, and clear 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 good parameter descriptions. The description adds meaning beyond schema by explaining the default model, the cost implication of _apiKey, and the return structure (per-model object with score, confidence, signals, raw_response + combined view). This complements 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model. It names the default model and optional Anthropic probe, distinguishing it from siblings like scan_competitor_ai_presence through specific functionality.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies context for when to use but does not provide explicit 'when-not' guidance or mention alternatives, though the targeting 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description explains that the tool routes queries to one of 3,547 tools across 819 sources and returns structured answers with stable citation URIs. This adds meaningful behavioral context about its internal operation and output format.

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

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

The description is front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and efficiently covers domains, mechanism, usage triggers, and examples. It is slightly long but every sentence adds value, with 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 the tool's complexity (router to many sources), the description provides a good overall picture: purpose, usage context, input format, output characteristics (structured + citations). It does not discuss limitations or error handling, but with openWorldHint and no output schema, it covers the essentials.

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 input schema already documents all parameters well. The description adds minimal extra parameter semantics beyond examples; it does not explain each alias individually. Baseline of 3 is appropriate as the schema carries the semantic load.

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 tool for answering questions about current or historical data using structured sources, with explicit preference over web search. It lists many specific domains and provides examples, making the purpose unambiguous and distinct from siblings like 'web search' or 'entity_profile'.

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 recommends using this tool over web search for factual questions about real-world entities, and provides a list of trigger phrases ('what is', 'look up', etc.) and examples. It lacks explicit mention of when NOT to use it (e.g., subjective or creative questions), but the 'PREFER OVER WEB SEARCH' framing gives strong 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 read-only, open-world, idempotent, non-destructive traits. Description adds valuable behavioral details: explicit refusal reasons (not_in_source, no_tool_match, etc.), extra LLM call cost, and extraction method. No contradiction with annotations.

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

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

Description is front-loaded with purpose and structure, using concise but complete sentences. Every sentence adds value: purpose, contrast, use cases, return format, refusal reasons. No redundant or vague statements.

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, description fully specifies return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists all refusal reasons. Explains the extra LLM call and contrasts with sibling. Comprehensive for a tool with 3,641 sources and high-stakes 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% with all six parameters documented including aliases and natural language examples. The description does not add parameter-specific semantics beyond what schema provides; it focuses on overall behavior. 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 it's a 'hallucination-resistant answer mode' for high-stakes reads, distinct from sibling ask_pipeworx. It specifies the action (extracts answer using ONLY tool result) and the resource (same routing as ask_pipeworx but with extra safety).

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 use when 'an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Contrasts with ask_pipeworx, noting cost difference and preference for casual lookups, providing clear when-to 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?

Description adds no behavioral context beyond annotations; annotations already indicate read-only, idempotent, non-destructive 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?

Extremely brief but under-specified; lacks core information, not conciseness in a good sense.

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?

Does not explain input or output despite known output schema; misses essential details like decoding process or return type.

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?

Parameter 's' is completely undocumented in description; schema coverage is 0% and description adds no 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?

Description 'Base64 decode' is essentially a tautology of the tool name, providing no additional clarity on what it does or distinguishes it from siblings.

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

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

No guidance on when to use this tool, no mention of alternatives like base64_encode, and no context for appropriate scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds no behavioral context. It does not mention any output or side effects.

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

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

Extremely brief but not concise in a helpful way. The single sentence adds no value beyond the tool name, resulting in underspecification rather than efficiency.

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, a more complete description ('Encodes a string to a Base64 string') would suffice. Current description leaves ambiguity about what is encoded and what 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?

The single parameter 's' has no description in the schema (0% coverage) and the description does not clarify its meaning. The description fails to compensate for the lack of schema documentation.

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 'Base64 encode.' indicates the general action but lacks specificity about the input and output. It does not distinguish from sibling base64_decode except by name, which is already inherent.

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

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

No guidance on when to use this tool over alternatives like base64_decode or other encoding methods. The context of use is entirely implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details: fan-out logic, classifier list, error handling (GDELT 429s, GNews fallback), safety mechanisms (low-confidence short-circuit, market closed status), and response shape breakdown. 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 thorough but lengthy, spanning multiple paragraphs. It front-loads the main purpose and has a logical structure (purpose, classifiers, fan-out, response shapes, edge cases). However, it could be more concise by summarizing some 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 tool complexity (3 params, no output schema), the description is exceptionally complete. It covers resolver contract, parent event extraction, news fields, safety notes, and fan-out examples. Agents have sufficient information to understand expected responses and handle edge cases.

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 each parameter well-described (market input formats, depth enum, include_raw purpose). The main description adds context like fan-out examples but does not significantly enhance parameter semantics beyond schema.

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

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

The description explicitly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb+resource ('Research a Polymarket bet'). It distinguishes from sibling tools like polymarket_edges by describing comprehensive fan-out and evidence packet return. Use cases like 'should I bet on X' are clear.

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 (e.g., 'should I bet on X') and includes examples of fan-out for different bet categories. However, it does not explicitly state when not to use or directly compare to siblings, though the use cases imply differentiation.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: company type pulls latest 10-K data handling off-calendar fiscal years; drug type pulls FAERS, FDA approvals, trial counts; results sorted by primary metric; returns citation URIs.

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 paragraph packed with essential info, front-loaded with trigger phrases and preference. Slightly dense but efficient; could be broken into sections but remains readable.

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

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

No output schema, but description explains return format (paired data + citation URIs). Covers data sources for both types. Lacks explicit error handling or rate limits, but adequate for complexity.

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

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

Schema coverage 100%, baseline 3. Description adds examples of tickers/CIKs for company and names for drug, clarifies max/min items, and distinguishes parameter usage beyond schema enum 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 side-by-side comparison of 2–5 companies or drugs, lists trigger phrases like 'Compare X and Y', and specifies data sources for each entity type. 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides context for choosing company vs drug type. Lacks explicit exclusions for non-comparison scenarios, but implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds no behavioral detail beyond these hints. Since annotations carry the transparency burden, score is baseline 3.

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

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

Although very short, the description fails to be meaningful. Its two words do not earn their place because they lack any informative 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 having an output schema, the description does not hint at the return value (e.g., cookie key-value pairs). The tool's purpose remains unclear, leaving the agent underinformed.

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?

Tool has zero parameters, so schema coverage is 100% by default. The description does not need to add parameter info. Baseline 4 for no 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?

Description 'Caller cookies.' is vague and tautological; it does not specify any action (e.g., get, list, manage) nor what resource is accessed beyond the tool name. It fails to differentiate from siblings like 'get' or 'headers'.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., 'get' for general headers, 'ip' for IP info). The description does not mention any prerequisites or context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect transparency. The description adds no extra behavioral context beyond the literal action of sleeping, and does not contradict annotations.

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

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

The description is extremely concise at four words, with every word earning its place. It is front-loaded and efficient, though a bit more detail on parameter limits or behavior would improve completeness without sacrificing 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?

For a simple tool with one required parameter and existing annotations, the description provides the minimum viable information. It does not mention return values or any output schema details, but the tool's simplicity and annotation coverage make it adequate.

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

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

With 0% schema description coverage, the tool description must compensate. The phrase 'Sleep N seconds' only restates the parameter name 'seconds' without adding details like valid range, units, or constraints. The parameter's type (number) and its purpose are minimal.

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 'Sleep N seconds' clearly indicates the tool's function: it pauses execution for a specified duration. There is no ambiguity, and it distinguishes itself from all sibling tools, none of which offer a delay 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?

No explicit guidance on when to use or not use this tool is provided. However, since there are no sibling tools with similar functionality, the lack of alternatives makes the usage context implicit. The description does not offer exclusions or 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 indicate read-only and idempotent. The description adds that it returns top-N relevant tools with full schemas and that results are ready to call directly, providing useful 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 well-structured and front-loaded with the main purpose. It is relatively concise, though slightly verbose, but 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?

Despite no output schema, the description explains what is returned (names, descriptions, schemas) and that results are ready to call. Given the tool's role as a discovery tool among many siblings, it is fully complete.

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

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

Schema description coverage is 100%, so baseline 3. The description does not add significant parameter semantics beyond what the schema already provides, though it mentions the query parameter meaning.

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

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

The description clearly states the tool finds tools based on a description of data or task, listing many example domains. It distinguishes itself from siblings by being a discovery tool.

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

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

The description explicitly says '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).'

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. Description adds significant behavioral context: it fans out across multiple sources, returns specific data fields (cik, company_name, filings, fundamentals, patents, news, LEI), notes that patents API sunset will cause soft-fails, and specifies input requirements. No contradiction with annotations.

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

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

Description is relatively long but each sentence adds value. It uses a clear structure with examples, usage guidance, and a detailed list of return data. While it could be slightly more concise, the information density justifies the 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 (multiple data sources, no output schema), the description is remarkably complete. It lists all return fields, explains the patents sunset soft-fail, specifies input restrictions, and provides usage guidance. This covers nearly all necessary contextual information 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?

Input schema has 100% description coverage, defining type (enum 'company') and value (string). Description reinforces these semantics, adding that value can be ticker or zero-padded CIK, and names are not supported. This adds extra clarity beyond schema alone, justifying a high score.

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's purpose: obtaining a full cross-source profile of a US public company in one parallel call. It also provides user query examples like 'Tell me about X' and 'company profile for Microsoft', and distinguishes itself from chaining single-pack lookups.

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

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

Explicitly states preference over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. Also specifies that names are not supported, directing users to use resolve_entity first. Provides clear context for when to use this tool vs 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 destructiveHint=true and idempotentHint=true. The description confirms the destructive nature by stating 'Delete'. It adds no extra behavioral context beyond what annotations provide, so the additional value is limited.

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 covering purpose, usage guidelines, and sibling relationship. Every sentence adds value with 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 the simplicity of the tool (one required parameter, no output schema, annotations present), the description adequately covers purpose and usage. However, it does not mention the return behavior or confirm idempotency, which would be helpful for completeness.

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

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

Schema coverage is 100%, and the schema describes the 'key' parameter as 'Memory key to delete'. The description merely mentions 'by key' without adding semantic detail. Thus, the description adds no significant meaning beyond the schema.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It is distinct from sibling tools like 'remember' and 'recall', which store or retrieve memories.

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 when to use the tool: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with 'remember' and 'recall'. However, it does not provide explicit when-not-to-use scenarios.

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

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

Annotations already indicate safe read-only behavior. Description adds detail: fetches page, extracts title/description/key links, outputs llms.txt format. 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 plus a bullet list for use cases. Front-loaded with purpose and process. Efficient 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?

No output schema, but description explains output as 'single text blob' for site-root/llms.txt. Parameters are covered. Annotations cover side effects. Complete for a simple generation 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 repeats schema descriptions for url and max_links without adding extra meaning. The default and max for max_links are already in schema.

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

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

Clearly states what the tool does: generate a llms.txt file for a URL. The verb 'generate' and the specific resource 'llms.txt' are clear. However, it does not explicitly distinguish from sibling tools like robots_txt or scan_competitor_ai_presence, though the unique purpose is evident.

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 use cases: getting a client's site indexed, drafting own llms.txt, auditing competitor. Does not explicitly state when not to use or list alternatives, but the usage 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 declare the tool as read-only, idempotent, and non-destructive, which is consistent with a GET operation. However, the description does not add behavioral detail beyond the annotations, such as what 'echo' means or any side effects.

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

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

The description is extremely concise (3 words), but it sacrifices clarity and completeness. While brevity is valued, this lacks essential context to be useful.

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

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

Despite having an output schema and rich annotations, the description fails to explain the tool's core functionality. It is incomplete, leaving the agent to infer that 'Echo a GET' means returning the request parameters or performing a dummy GET request.

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

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

Schema description coverage is 0%, and the description does not mention the parameters (query, headers) or their purpose. Without parameter guidance, the agent cannot understand how to populate these fields.

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 'Echo a GET' is vague; it does not clearly state what action is performed (e.g., making an HTTP GET request) or what resource is targeted. The name 'get' hints at an HTTP verb, but the description adds little clarity and does not differentiate from the sibling 'post'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'post' or other sibling tools. The description is too brief to imply any context for usage.

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 no further behavioral context (e.g., output format, header listing behavior). It neither contradicts nor significantly extends 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 words and perfectly concise. Every word is necessary and contributes to 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 the tool's simplicity (no parameters, clear function, output schema exists), the description is complete. No additional information is required for correct use.

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

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

There are zero parameters, so the baseline is 4. The description does not need to add parameter meaning as there are none.

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 'Echo caller's headers.' clearly states the tool's function with a specific verb ('Echo') and resource ('caller's headers'). It implicitly distinguishes from siblings like 'cookies' and 'ip' which echo different request 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?

No guidance is provided on when to use this tool versus alternatives such as 'cookies', 'user_agent', or 'get'. The description offers no context for selection among siblings.

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

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

The description adds no behavioral context beyond the annotations. It says 'Sample HTML.' which is not behavioral. Annotations already convey readOnly, idempotent, non-destructive, and open-world 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?

Two words is concise but fails to provide meaningful information. The description is under-specified and does not earn 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?

Given zero parameters and existing annotations, the description still must convey the tool's purpose, which it fails to do. It is completely inadequate for understanding what the tool does.

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?

There are zero parameters, so the description has no burden to explain them. Baseline 4 applies per guidelines.

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 'Sample HTML.' is vague and does not convey the tool's purpose. It lacks a verb and resource, and does not differentiate from siblings like json_anything or xml_anything.

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

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

No guidance on when or when not to use this tool. With many siblings, the description offers no context for selecting 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 indicate readOnly, idempotent, openWorld, and non-destructive behaviors. The description adds only that it returns a URL, which is implied by the output schema. No new behavioral traits are disclosed beyond what annotations cover.

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

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

The description is very short and to the point, but the word 'Sample' may be unnecessary. Overall, it is appropriately concise for a simple tool.

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

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

Given the tool's simplicity and the presence of an output schema, the description is adequate but fails to clarify valid format inputs. It meets the minimum threshold but has a clear gap.

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 has 0% description coverage, and the description does not explain the 'format' parameter, its allowed values, or its role. The examples in the schema partially compensate, but the description itself adds no semantic 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?

The description states it returns image metadata (a URL) for a given format, which clearly indicates what the tool does. However, the term 'Sample' introduces ambiguity about whether the data is real or placeholder, slightly detracting from clarity.

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

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

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The sibling list is extensive but unrelated, and the description offers no context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add nuance. The phrase '(gateway egress)' clarifies that the IP is the egress point, not necessarily the client IP, which is valuable disclosure beyond annotations.

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

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

The description is a single, concise sentence with no unnecessary words. It efficiently conveys the tool's purpose.

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

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

Given the tool's simplicity (no parameters, output schema present), the description is sufficient. It explains the distinct nature of the returned IP and does not need to describe return values since output schema is available.

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?

There are zero parameters, so the description does not need to document parameter meanings. Schema coverage is 100% (empty object), and the baseline for 0 params is 4.

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

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

The description clearly states that the tool returns the IP address of the caller, specifically the gateway egress IP. This is a specific verb+resource pairing that is easily distinguishable from siblings like 'headers' or 'cookies'.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. While the purpose is clear, it lacks context such as 'use this when you need the network-level IP of the request' or 'if you need client IP, consider using headers instead'.

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 behavior. The description adds no behavioral context beyond 'Sample JSON', which does not inform about return format, size, or any side effects. No contradiction exists, but value added is minimal.

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

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

The description is extremely short (two words) but this sacrifices clarity. It is front-loaded but fails to be informative, thus it is under-specified rather than efficiently 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 an output schema but no parameters, the description should at least hint at the sample's content or behavior. 'Sample JSON' is insufficient for an agent to predict what will be returned, especially without further context from the 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?

No parameters exist; schema coverage is 100%. The description adds the vague notion of 'sample' but for zero-parameter tools the baseline is 4. The description does not detract from schema clarity.

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 'Sample JSON' is vague and nearly tautological with the tool name 'json_anything'. It lacks a specific verb and resource, making it unclear whether the tool generates, returns, or validates a JSON sample. The purpose is only weakly implied.

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

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

No guidance on when to use this tool versus siblings like html_anything or xml_anything. The description provides no context, prerequisites, or exclusions, leaving the agent without 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, destructiveHint=false, and idempotentHint=true. Description adds that it lists active subscriptions (with optional include_inactive) and specifies return fields, which is adequate additional 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 two sentences: first states purpose and returned fields, second gives 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?

For a simple list tool with no output schema, the description lists all returned fields, covers the single optional parameter via schema, and annotations handle behavioral safety. 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 coverage is 100%, and the single parameter 'include_inactive' has a clear description in the schema. The tool description does not add extra parameter details, meeting the baseline.

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

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

Description clearly states 'List the caller's active subscriptions' and lists returned fields, providing a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving specific contexts for tool use. While it doesn't mention when not to use it, no direct alternative exists among siblings.

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

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

Discloses rate limits (5 per identifier per day), free usage, no quota impact, and signal effect on roadmap. No annotation contradictions.

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

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

Concise, front-loaded with purpose, each sentence adds value. No fluff.

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

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

Given no output schema, description covers purpose, usage, constraints, and rate limits, providing complete context for 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?

Schema coverage is 100%, baseline 3. Description adds extra guidance like not pasting prompts and explains type enum values, adding value beyond schema.

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

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

Description clearly states the tool sends feedback to the Pipeworx team about issues, missing features, or praise. It distinguishes from sibling tools by specifying feedback scenarios.

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

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

Explicitly lists when to use (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Provides structured 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This goes 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 a single paragraph of about 4 sentences, front-loaded with the core purpose, then use cases, then technical details. It is well-structured and concise, though could be slightly shorter without losing clarity.

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

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

The description covers purpose, usage, transparency, and caching, but lacks detail on the output structure. Since there is no output schema, a brief description of the return format (e.g., keys, counts) would improve completeness 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 enum and description for the 'window' parameter. The description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaningful guidance beyond the schema's basic enumeration.

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: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It specifies the verb (returns), resource (top tools/packs/call volume), and scope, distinguishing it from siblings like ask_pipeworx or pipeworx_feedback.

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 tools, and aligning use cases. It also gives guidance on window selection ('shorter windows surface what's hot right now; longer windows show steady-state demand'). Missing explicit when-not-to-use, but the context is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details behavioral traits: walking child markets, checking monotonicity, partition-check computation, semantic anchor (Jaccard similarity >= 0.30), partition filter for placeholder slugs, and response structure. 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 lengthy but well-structured, with a clear requirement statement followed by detailed mode explanations and filters. Every sentence adds value, though some redundancy could be trimmed.

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 response structure, edge cases (low similarity, placeholder filters), and mode-specific behavior. Without an output schema, it provides adequate context, though error handling could be expanded.

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 parameter descriptions. The description adds meaning by explaining how each parameter triggers different modes (event vs topic), provides example values, and describes associated behaviors.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) with distinct use cases, distinguishing it from siblings like 'polymarket_edges' and 'polymarket_kalshi_spread'.

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 requires one of 'event' or 'topic', warns that no args fails, and recommends each mode with examples. It provides clear guidance on when to use each, though it does not compare against sibling tools.

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

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

The description is highly transparent, detailing three model families, response structure, diagnostics, caching (1h at KV level), and edge attributes. Annotations confirm readOnly, idempotent, non-destructive; description adds no contradictions and enriches understanding of 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 long but well-structured with sections on segments, response fields, and knobs. Front-loaded with purpose, each sentence adds value. Slightly verbose but justified by tool complexity.

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

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

Given the tool's complexity (9 params, no output schema), the description thoroughly covers purpose, segments, response fields, diagnostics, and caching. It provides enough detail for an agent to understand input, output, and edge cases.

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

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

Schema coverage is 100%, baseline 3. The description adds context for parameters like min_liquidity ('thin-book opportunities where executing the edge would walk the book past breakeven') and min_kelly ('skips opportunities that are too small'), improving usability beyond schema alone.

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

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

Clearly states the tool scans Polymarket markets for opportunities where Pipeworx data diverges from market price, distinguishing it from sibling tools like polymarket_arbitrage. The verb 'scan' and resource 'Polymarket markets' are specific, and the title and description align.

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

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

The description implies usage for discovering betting opportunities but does not explicitly state when not to use it or provide alternatives among siblings. The mention of 'what should I bet on today' gives context, but no direct comparison to other tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: delta is a real signal when bet shapes match, compatibility_warning conditions (non-equivalent shapes, unrelated events), temporal alignment, and skipped comparison counters. 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 dense and well-structured, front-loading purpose and modes, then detailing response fields and safety warnings. Every sentence is useful, but it could be slightly more concise. Still, appropriate for the complexity.

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

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

Given the complexity and lack of output schema, the description fully explains the response structure (leg prices, matched spreads, compatibility_warning, temporal_alignment). It covers edge cases and safety fields, leaving no 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%, but the description adds significant meaning: explains the two modes, lists topic shortcuts, and describes how explicit parameters override topic mappings. The examples in schema reinforce this. 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 clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, distinguishing it from siblings like polymarket_arbitrage. It specifies the resource (same resolving question) and actions (auto-fetch, matched spread).

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

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

The description provides explicit guidance on when to use (seeking cross-venue spreads), warns about non-equivalent bet shapes via compatibility_warning, and explains two modes (topic shortcuts vs explicit event IDs). It advises that pre-mapped topics are often not tradeable.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, which the description does not contradict. However, the description adds no behavioral details beyond 'echo', missing information about idempotency confirmation, return behavior, or any side effects.

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

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

The description is extremely concise at three words, but this brevity sacrifices clarity. The single sentence does not provide enough information to be useful, making it an example of under-specification rather than effective conciseness.

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

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

Given the tool has three parameters, annotations, and an output schema, the description is far too minimal. It does not explain return values, usage with parameters, or how it relates to other tools, leaving an agent without essential 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 description coverage is 0%, so the description must compensate. The description does not mention any of the three parameters (body, headers, content_type), leaving their purpose entirely unexplained despite examples in the schema.

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

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

The description 'Echo a POST' is vague and nearly tautological with the tool name. It suggests a simple echo of a POST request but does not clearly specify the action or output, failing to distinguish from siblings like 'get' or 'headers'.

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

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

No guidance is provided on when to use this tool versus alternatives. There are many sibling tools, and without usage context, an agent cannot determine appropriate scenarios for this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping detail (anonymous IP, BYO key hash, account ID) beyond annotations, 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, each purposeful: core function, use case, scoping, pairing with siblings. Front-loaded and 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?

For a single-optional-parameter tool with no output schema, the description fully explains behavior (list all if key omitted), scoping, and sibling relationships. No gaps.

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

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

Schema coverage is 100% and its description covers omitting key to list all. Description repeats this, adding no new semantic detail, so baseline 3 applies.

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

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

The description uses specific verb 'Retrieve' and resource 'value previously saved via remember', clearly stating the tool's function and distinguishing from siblings like 'remember' and 'forget'.

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

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

Explicitly says to use for looking up context stored earlier, scoped to identifier, and pairs with remember/forget. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds key behavioral detail: mark_read:true flags events as read, affecting subsequent calls. No contradictions.

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

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

Three sentences: purpose, field details and filtering, alternative access. Each sentence is necessary and front-loaded. 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?

Covers all aspects: return fields, filtering, mark_read side effect, polling suitability. With no output schema, describing returned fields is essential. The alternative endpoint is helpful for integration.

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 parameters with descriptions. Description adds context: example type 'sec_8k', clarifies 'since' as ISO timestamp, explains effect of mark_read and unread_only. 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?

Clearly states 'Pull fired events from your subscription feed' with specific verbs and resources. Distinguishes from sibling tools like list_subscriptions by focusing on recent alerts and mentioning the feed.

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 guidance on polling and an alternative endpoint for scripts/dashboards. Could explicitly state when not to use or compare with list_subscriptions, but the context is clear.

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

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

Discloses fan-out behavior across SEC EDGAR, GDELT→GNews with fallback, USPTO soft-failure, and output structure (grouped by source, total_changes, citation URIs). Annotations already declare safety (readOnlyHint), and description adds significant behavioral context beyond them.

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

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

Single dense paragraph, front-loaded with common queries. Every sentence contributes value, but could be more scannable with structure (e.g., bullet points) 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?

Complete coverage: explains all parameters, output shape, source behavior, fallbacks, and alternative tool. No gaps given annotations presence and lack of 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?

Adds meaning beyond schema: explains since format (ISO date or relative shorthand) with examples, value as ticker or CIK, and type constraint. Schema coverage is 100%, but description enriches understanding with usage guidance.

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

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

Description clearly states the tool provides a change feed for a company across multiple sources, using specific verbs and examples like 'What's new with X' and 'updates on Acme'. It also distinguishes from sibling tool entity_profile, establishing a unique purpose.

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

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

Explicitly states when to use this tool (for changes over time) versus entity_profile (for static profiles). Provides example queries and recommended default for since parameter, guiding appropriate invocation.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds scoping by identifier and retention details (persistent for authenticated, 24 hours for anonymous). However, it doesn't clarify behavior on overwriting an existing key, which is relevant given idempotency.

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?

Multiple sentences but each adds value. Front-loaded with core purpose, followed by usage, pairing, and persistence details. Could be slightly more concise, but 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 no output schema, description adequately covers storage behavior and pairing with recall/forget. Missing detail on idempotent behavior (overwrite vs ignore) for existing keys, but overall complete enough for a storage 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 already describes key and value with examples, achieving 100% coverage. The description adds usage context (e.g., 'findings, addresses, preferences') and reinforces the key-value nature, going slightly beyond the schema.

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

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

The description uses specific verbs ('Save data', 'reuse later') and provides examples of what to store (resolved ticker, target address, user preference, research subject). It clearly distinguishes from sibling tools 'recall' and 'forget' by describing the complementary actions.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides context on persistence (authenticated vs anonymous sessions) and pairs with 'recall' and 'forget' for retrieval and deletion, offering clear alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint true; the description adds that internally it cascades through several endpoints, replacing 2-3 manual lookups. This provides useful behavioral context beyond the annotations, without contradiction.

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

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

The description is a single paragraph that front-loads with common query examples, then clearly states the purpose, usage, supported types with input/output details. Every sentence adds value, with no redundancy or 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 tool's complexity (two entity types, multiple input formats, internal cascading lookups) and no output schema, the description adequately explains inputs, outputs (including URIs), and automatic disambiguation for company. It does not cover error cases (e.g., ambiguous or missing entities), but overall provides sufficient context for an AI agent to use the tool effectively.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing specific input examples (ticker, CIK, company name for 'company'; brand/generic name for 'drug') and detailing the output format (identifiers, URIs), going beyond the schema's minimal descriptions.

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

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

The description clearly states it resolves a spoken name to a canonical identifier, with concrete examples like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes itself from sibling tools by focusing on entity resolution for identifiers needed by 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not mention when not to use or alternative tools, but the context implies it is the dedicated entity resolution tool among siblings.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive, but the description adds no behavioral context beyond those structured fields. The minimal description fails to leverage the opportunity to add value.

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

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

Extremely short but under-specified. Not just concise—it lacks necessary information. A concise description should still be 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?

Given the tool's apparent purpose (handling robots.txt), the description provides zero context about input, output, or behavior. An output schema exists but the description doesn't mention what is returned.

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

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

No parameters exist, and schema coverage is effectively 100%. Baseline 4 applies since there are no parameters to describe; the description cannot add parameter meaning.

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

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

Description is tautological: 'Sample robots.txt.' It does not specify what the tool does, e.g., fetch or analyze robots.txt files. Restates the name without adding meaning.

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

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

No guidance on when to use this tool versus siblings like get or scan_dependency. No context about appropriate scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds valuable behavioral info: it internally uses ai_visibility_check, aggregates results, treats first entity as subject, and returns ranked list with 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?

Three sentences, front-loaded with purpose, no fluff. Every sentence adds value: function, method, use case. Highly 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?

Given 4 parameters (1 required) and no output schema, the description adequately explains the output format (ranked list with score, confidence, signal density). It also covers the array length constraint and first-entity treatment. Complete for a comparison tool with rich annotations.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, including that entities first entry is subject. The main description does not add significant new meaning beyond the schema, so 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 clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (general comparison) by specifying AI visibility focus and output details.

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

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

The description provides context for competitive AI-marketing audits and poses a concrete question. It implicitly suggests using the sibling ai_visibility_check for single entities, but does not explicitly state when not to use this tool or provide alternative names.

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

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

Annotations already convey read-only, idempotent, non-destructive nature. Description adds critical behavioral details: partial failure handling (bundlephobia may timeout, sources_failed listed), graceful degradation, and measurement latency (5-30s). Contradiction is false.

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

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

Description is concise yet comprehensive. Front-loaded with core purpose, then efficiently covers ecosystem, timing, and output format. Every sentence adds value with 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 the absence of an output schema, the description fully explains the return value structure (summary block fields, per-advisory detail, links, alternative versions) and edge cases (timeout, partial failures). This makes the tool's behavior predictable and complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal param detail beyond schema: mentions that scoped packages are accepted and that version defaults to latest. This is adequate but not extensive; extra context about return value shape compensates slightly, but is not about 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?

Description clearly defines the tool as a composite check for npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings by specifying the ecosystem and multi-source aggregation, leaving no ambiguity about what resource is being scanned.

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

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

Explicitly states when to use: 'when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides exclusion guidance for non-npm ecosystems, directing to deps.dev:version directly, which helps avoid misuse.

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 technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag. Output includes character offsets and similarity scores. No contradiction with annotations (readOnlyHint=true).

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

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

Description is front-loaded with core purpose, then usage, then technical details. Every sentence adds value; no wasted words. Appropriate length for a moderately complex tool.

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

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

Even without output schema, the description sufficiently explains output format (passages with offsets and scores) and input constraints (200K char limit with truncation). Covers edge cases and pairing 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%, so baseline is 3. Description adds value with concrete examples for query and text, explains default and range for limit, enhancing understanding 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?

The description clearly states the tool does semantic search inside a fetched record, providing concrete examples (SEC 10-K, article) and detailing output (top-N passages with offsets and scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: when the record is too big for the prompt. Mentions pairing with ask_pipeworx_grounded for grounding over relevant passages, providing clear guidance on 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 readOnly, idempotent, not destructive. Description adds no behavioral context (e.g., what happens when status is returned, whether it simulates a response, any side effects). Fails to add value beyond 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?

Single sentence is concise but under-specified. No structure beyond a minimal verb-object phrase. Could be more informative without adding length, but not excessively verbose.

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

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

Despite having one parameter and an output schema, the description is too brief to be complete. Does not mention what the tool returns (output schema exists but ignored), nor any constraints or behavior that would help an agent use it 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 has 0% parameter description coverage. Description mentions 'given HTTP status' but does not explain the 'code' parameter, its valid range, or relationship to HTTP status codes. Fails to compensate for missing 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 is a tautology: name is 'status', description says 'Return given HTTP status.' It adds 'given HTTP' but doesn't clarify what exactly is returned (e.g., status code, status page). Does not distinguish from sibling tools like 'get'.

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

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

No guidance on when to use this tool vs. alternatives. No context about prerequisites, scenarios, or exclusions. Agent receives no help deciding between 'status' and other 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 (readOnlyHint=false, idempotentHint=true) are provided, so the description's burden is lower. It adds behavioral context like OAuth requirement and SMS rate limits. However, it does not clarify idempotency behavior (e.g., whether duplicate subscriptions are allowed), which is expected given idempotentHint=true.

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

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

The description is fairly long but well-structured with clear sections (supported types, delivery channels). It front-loads the main purpose and return. Some redundancy could be trimmed, but overall efficient for a complex tool.

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

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

Given the tool's complexity (3 params, multiple types, delivery channels, authentication), the description covers all essential aspects: types and their params, delivery options, authentication, return value, and even notes on rate limits and alternative retrieval. It is sufficiently complete for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by providing detailed examples for each type, explaining the patent_grant approximate matching note, and elaborating on delivery channels. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription ID. It specifies the verb 'Create' and the resource 'subscription to live-data event stream'. This distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides explicit context: requires a Pipeworx OAuth account, not for anonymous/BYO. It explains when to use it (proactive monitoring) and gives examples for each supported type and delivery channels, including limitations (SMS 10/day cap). It does not explicitly state when not to use it, but the sibling tools cover other operations.

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 soft-delete behavior (deactivated not deleted) and references historical events, supplementing annotations.

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

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

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

Adequate for a simple tool; mentions outcome and side effect. Could detail return value, but overall complete.

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

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

Schema coverage is 100%, description adds 'by id' and 'uuid' but adds little 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+resource: 'Cancel a subscription by id.' Distinguishes from siblings like subscribe and list_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?

Specifies ownership enforcement but does not explicitly compare to alternatives 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 readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds minimal context beyond a summary. 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?

Extremely concise, but lacks a complete sentence. However, for such a simple tool, it is acceptable.

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 parameters, rich annotations, and an output schema, the description is minimally adequate. However, it could clarify that it returns the user agent string.

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

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

No parameters; schema coverage is 100% by default. The description does not need to explain parameters, but could elaborate on the output.

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 the caller's user agent. It is specific and distinguishes from siblings as a simple read-only utility.

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

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

No guidance on when to use this tool versus alternatives. No context on limitations or when it might be inappropriate.

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, fully covering behavioral traits. The description adds no additional context beyond what annotations provide, so it is adequate but not enhanced.

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

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

The description is extremely concise with two words, no wasted information, and perfectly appropriate for such a simple tool.

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

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

Given the tool has no parameters, an output schema exists, and annotations are rich, the description is complete and sufficient 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?

There are no parameters, so baseline is 4. The description does not need to add parameter meaning as none exist, and schema coverage is 100%.

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 'Random UUID' clearly states the tool generates a random UUID, which is a specific verb and resource. It is unique among siblings, so no differentiation needed.

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 implicitly suggests using this tool when a UUID is needed but provides no explicit guidance on when to use versus alternatives, nor any exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that the tool replaces 4-6 sequential calls and details return values (verdict, structured form, actual value with citation, percent delta). 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 moderately concise, front-loading usage patterns and then explaining scope and return. Slightly longer than necessary but each sentence adds value. Well-structured.

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

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

Given the single parameter, rich annotations, and no output schema, the description covers usage, scope, and return values adequately. Minor omission: no mention of error handling or that only US public companies are supported, but overall 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% with a description of the 'claim' parameter. The description adds context (natural-language claim, examples) but does not significantly extend beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool does claim verification against authoritative sources, with specific examples of user queries ('Is it true that...', 'fact check') and a targeted domain (company-financial claims). It distinguishes itself from siblings like 'compare_entities' and 'entity_profile' by focusing on factual verification.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates scope (v1 supports company-financial claims). No explicit when-not-to-use or alternatives, but the 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?

The description adds no behavioral context beyond what annotations already provide. Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description fails to explain these or any additional traits.

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

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

The description is extremely concise but at the expense of clarity. It is under-specified and fails to convey essential information.

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

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

Given the tool has no parameters but has an output schema and annotations, the description is incomplete. It does not explain what 'Sample XML' means or how the tool is intended to be used.

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?

Although there are no parameters and schema coverage is 100%, the description does not add any semantic value. It neither clarifies the purpose of the tool nor explains what the output (which exists) represents.

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 'Sample XML' is a vague label that does not specify what the tool does. It lacks a verb or any indication of functionality, making it impossible to distinguish from siblings.

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

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

No guidance is provided on when to use this tool vs alternatives. The description offers no context or examples of appropriate use cases.

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