Japan Law

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: it explicitly states the default model is free, that Anthropic probing requires a BYO key passed to api.anthropic.com, and that the response structure includes per-model scores and a combined view. This goes beyond annotation declarations.

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

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

The description is concise (3-4 sentences), front-loaded with the action and outcome, and structured to convey purpose, usage, and return format efficiently. No word is wasted.

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

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

Given no output schema, the description sufficiently explains the return format (per-model score, confidence, signals, raw_response + combined view) and covers all parameters and use cases. It provides enough detail for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the purpose of each parameter: `_apiKey` is only needed for Anthropic, `context` helps disambiguate, `models` can be omitted for default. This enriches the schema.

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

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

The description clearly states it probes LLMs for knowledge of a business/brand/product/topic and returns a visibility score per model. It distinguishes itself from sibling tools like compare_entities and deep_research by focusing on AI visibility measurement.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions key details like default model and API key requirement. However, it does not explicitly say when NOT to use it or compare to alternatives.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context about returning structured answers with citations and routing to many sources, going beyond annotations.

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

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

The description is well-structured with clear directives and examples, but is somewhat lengthy. Most sentences add value, but could be slightly condensed.

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

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

Despite lacking an output schema, the description fully explains the tool's behavior, output format (structured answer with citations), and appropriate usage, making it complete for this complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description provides no additional semantic detail beyond what the schema already specifies for the parameters.

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

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

The description explicitly states the tool's purpose: routing questions to appropriate tools/sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Detailed guidance is provided on when to use this tool over web search, with examples and explicit alternatives. It says 'START HERE for most questions' and 'Step up only when needed', making the decision 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 that it uses only tool results, returns explicit refusal reasons, and costs one extra LLM call. This adds value beyond annotations (readOnlyHint, etc.) and does not contradict 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?

Description is well-structured with a clear first sentence, detailed behavior explanation, and usage guidance. It is informative but could be slightly more concise; however, every sentence serves a 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 no output schema, the description explains the return value structure and possible refusal reasons. It also mentions cost implications. For a complex tool with many siblings, this is highly complete.

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

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

Schema description coverage is 100% with each parameter having a description. The description adds minimal extra meaning beyond 'Your question in natural language' and listing aliases. 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?

Explicitly states it is a 'hallucination-resistant answer mode for high-stakes reads', distinguishing it from sibling ask_pipeworx which is for casual lookups. Verb 'answers' and resource 'tool results' 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?

Provides explicit when-to-use scenarios: 'whenever an answer will be quoted, cited, or acted on' and lists specific domains. Also explicitly says to prefer ask_pipeworx for casual lookups, giving 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?

The description extensively discloses behavioral traits beyond annotations. It details safety measures (low-confidence resolution short-circuit, closed market handling), tradeability warnings (wide spreads), resolution-rule parsing, resolver contract (confidence levels, alternatives), and fan-out logic with examples. No contradiction with annotations (readOnlyHint=true, destructiveHint=false).

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

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

The description is very lengthy (over 300 words) and includes detailed examples of fan-outs, response shapes, and edge cases. While informative, it lacks conciseness and could be structured more efficiently for quick parsing by an AI agent. The first sentence effectively summarizes the tool, but subsequent details are verbose.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is exceptionally complete. It covers input formats, resolution logic, fan-out behavior, return fields (market, analysis, evidence), security/safety mechanisms, and edge cases. No output schema exists, but the description thoroughly documents response shapes.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. The description adds extra context: it explains the recommended use of include_raw=false, gives examples of market input formats, and elaborates on the depth parameter through fan-out examples. This adds meaningful 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'Research', the resource 'Polymarket bet', and the outcome 'evidence packet + market-vs-model comparison'. It also lists classifier types and examples of fan-outs, making the purpose highly specific and distinguishable from sibling tools like polymarket_edges or ask_pipeworx.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This provides clear usage context. While it does not explicitly exclude alternative tools, the use cases are well-defined and align with the tool's purpose.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds detail on data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is front-loaded with query examples, uses bullets implicitly, and every sentence adds unique value. No redundancy or fluff.

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

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

Given the tool's two parameters and high schema coverage, the description covers behavior for both entity types, sorting, and return value structure (paired data + citations). It is complete for an AI agent to select and invoke.

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

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

Schema coverage is 100% but description adds examples for values (tickers/CIKs vs drug names) and explains how type determines data fetched. This adds meaningful context beyond schema enums.

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

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

The description explicitly states that the tool performs side-by-side comparison of 2-5 companies or drugs in one call. It provides example queries and distinguishes from sibling tools by noting it replaces sequential 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?

It explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. While it lacks explicit when-not-to-use, the context is clear and no alternatives are needed given its purpose.

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

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

Description adds significant context beyond annotations: the tool is not open-web, uses structured data only, returns gaps for unanswered facets, operates in parallel with high latency (15-60s), and has account tiers. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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 well-structured with parenthetical details and bullet-like lists. Every sentence adds necessary information (account, alternatives, behavior, output, timing). Could be slightly condensed but remains clear.

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

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

Given the tool's complexity (parallel research), no output schema, and 100% parameter coverage, the description adequately describes the return structure (findings packet with evidence, confidence, source, fetched_at, citation, gaps) and explains when results may be empty. Also mentions expected latency, which is useful 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 has 100% coverage with descriptions for both parameters. The description adds value by explaining the 'depth' enum meanings (quick=3, standard=5, thorough=8) and reaffirming that 'question' can be broad/multi-part in natural language, which enriches the schema semantics.

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 performs grounded multi-source research across 1160 structured data sources, decomposes questions, and returns findings with citations and gaps. It distinguishes from siblings like ask_pipeworx by specifying it is not open-web search and is best for broad/multi-part questions.

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

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

Explicitly provides when to use (broad/multi-part structured data) and when not to use (single lookup, breaking news, current events). Also details account requirement and alternative tool (ask_pipeworx) for unsigned users, with a note on paid plan for certain depth.

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 return of top-N tools with names, descriptions, and full input schemas, ready to call directly. Annotations already declare read-only and idempotent; description adds valuable output format details 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?

Front-loaded with purpose and usage guidance. Lists many domain examples, slightly verbose but each sentence adds value. Well-structured, but could be trimmed slightly.

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?

Completely describes the tool's role in the ecosystem given many sibling tools. Explains output (schemas, ready-to-call) and when to invoke. No output schema needed as description suffices.

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

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

Schema coverage is 100% with detailed parameter descriptions and examples. Description does not add additional semantics beyond listing aliases, which is already in schema. Baseline 3.

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

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

Clear verb 'find tools' with specific resource (tools) and scope (by describing data or task). Lists many domain examples. Distinct from siblings which are data-specific tools.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context and implied when-not (use other tools after discovery).

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details on fan-out across multiple sources, soft-fail for USPTO, and return fields.

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 somewhat long but front-loaded with examples and every sentence adds value. Could benefit from structured format.

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 enumerates return items (cik, filings, fundamentals, etc.) and mentions limits like 'up to 5 filings'. Adequate for a complex multi-source 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%, but description adds context like 'names not supported' and future plans for person/place, going 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 it provides a full cross-source profile of US public companies, with examples of user queries. It distinguishes from sibling tools like resolve_entity.

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

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

Explicitly says to prefer over chaining single-source lookups for holistic views, and advises using resolve_entity first if only a name is available.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not disclose additional behavioral traits beyond what annotations provide. 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 three sentences with zero fluff. The core action is stated first, followed by usage guidance and related tool mentions. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description provides complete context: what it does, when to use it, and how it relates to sibling tools. No gaps in information.

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

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

Schema coverage is 100%, so the schema already describes the 'key' parameter as 'Memory key to delete.' The tool description adds no extra detail about the parameter semantics beyond what the schema provides.

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

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

The description starts with 'Delete a previously stored memory by key,' which is a specific verb+resource. It also mentions pairing with 'remember' and 'recall,' clearly distinguishing the deletion functionality from its siblings.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It suggests pairing with related tools but does not explicitly state when not to use it or mention alternatives besides the siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool fetches the page, extracts title/description/key links, and emits standard markdown format. This complements annotations well. It could be improved by mentioning error handling or rate limits.

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

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

The description is concise: three sentences covering purpose, process, output, and use cases. It is front-loaded and contains no superfluous words.

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

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

Given the tool has two parameters, no output schema, and annotations present, the description covers purpose, process, output, and use cases adequately. It lacks details on error handling or edge cases, but for a straightforward tool it is fairly complete.

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

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

The input schema has 100% description coverage for both parameters. The description adds minimal extra meaning beyond the schema, as it does not directly explain the parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL to aid AI crawlers. It specifies the verb 'generate', the resource ('llms.txt file for URL'), and the outcome. This distinguishes it from sibling tools, none of which focus on llms.txt generation.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. However, it lacks explicit guidance on when not to use or alternatives, though the context makes it clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds important behavioral context: the full text is returned but truncated for long statutes, with a note confirming this. Source attribution is also provided. 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 two sentences with no wasted words. It front-loads the core action and provides all necessary details efficiently.

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 fetch tool with one parameter and no output schema, the description adequately covers what is returned (title, law number, etc.) and notes truncation. No gaps given the tool's complexity.

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

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

Schema coverage is 100% with a description for law_id. The description adds an example valid value and the context that it comes from e-Gov, enhancing understanding beyond the schema.

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

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

The description clearly states it fetches a Japanese law/ordinance by e-Gov law id, provides a specific example, and lists returned fields (title, law number, promulgation date, full text). It distinguishes itself from the sibling tool 'search_laws' by referencing it as the source for the law_id.

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

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

The description mentions 'from search_laws' indicating prerequisite use, and implies the tool is for when you have an e-Gov law id. While it doesn't explicitly state when not to use, it provides clear context. Notes truncation for long statutes adds practical 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 declare readOnlyHint, idempotentHint, etc. Description adds return field details and parameter behavior (include_inactive). No contradictions.

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

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

Two sentences, no redundant information, front-loaded with purpose and output fields.

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

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

Lists all return fields despite no output schema. Rich annotations compensate for missing info. Complete for a list 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 100% with parameter description. Description does not add additional meaning beyond what schema provides, baseline 3.

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

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

Explicitly states 'List the caller's active subscriptions' and lists returned fields. Distinguishes from sibling tools subscribe/unsubscribe by explaining usage context.

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

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

Provides clear use cases: 'review what you're monitoring before adding more or to find an id to cancel.' Could be more explicit about alternatives but context is clear.

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

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

Beyond the annotations (which are minimal), the description discloses that feedback is read daily, influences roadmap, is rate-limited to 5 per identifier per day, and is free/free of quota. This adds significant value over the annotations alone.

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?

Six sentences that efficiently convey purpose, usage, constraints, and behavioral notes. No redundant phrases; information is front-loaded and well-organized.

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

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

Covers all necessary aspects: what the tool does, when to use, how to structure input, rate limits, and business impact. No output schema is needed for a feedback submission tool. The description is complete given the tool's simplicity.

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. The description reinforces the intended use of the 'type' parameter by mirroring the usage categories, and advises using 'context' fields for tool/pack references. While schema already explains enums, the description adds practical context on how to structure feedback.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, or praise. It uses specific verbs ('Tell...something is broken, missing, or needs to exist') and identifies the resource (Pipeworx team). There is no sibling tool with similar functionality, so no distinction 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?

Explicitly lists when to use (bug, feature/data_gap, praise) and what to avoid (don't paste end-user prompt). Provides guidance on content (describe in terms of Pipeworx tools/packs) and mentions rate limits and quota behavior.

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

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

The description adds value beyond annotations by disclosing that data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. Annotations already declare readOnlyHint and idempotentHint, but the description provides operational details.

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

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

The description is three sentences, front-loaded with core purpose, and every sentence provides useful information. No fluff or 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 simple one-parameter nature, no output schema, and annotations covering safety, the description fully covers what the tool returns, how it works, and its caching behavior. It is complete for an agent to understand and invoke correctly.

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

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

The single parameter 'window' has a complete schema description covering the enum values. The description adds contextual meaning by explaining that shorter windows surface hot trends while longer windows show steady-state demand, which aids agent selection.

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 starts with a clear statement of what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This verb+resource combination is specific and distinguishes it from sibling tools like ask_pipeworx or discover_tools, which have different purposes.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming a canonical tool, seeing alignment) and explains the implications of different window choices. It does not name alternatives but the context makes when to use this tool 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 discloses extensive behavioral details beyond annotations, including the logic of monotonicity violations, partition-sum checks, Jaccard similarity threshold (≥0.30), placeholder fraction filter (>20% returns null), and fill check against live CLOB depth. Annotations already indicate readOnly and idempotent, and the description adds no contradiction.

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

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

The description is well-structured with clear sections but is relatively long. It front-loads the main purpose and then provides detailed algorithmic explanations. While every sentence adds value, it could be more concise without losing information. Still, it is organized and 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?

Despite having no output schema, the description fully specifies the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'in event mode partition_check{...}'. It also covers error conditions like null arb signals and fill check. This is complete for a complex tool.

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

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

Although the input schema has 100% coverage with descriptions for both parameters, the description adds significant meaning: it explains that event mode walks child markets and computes partition_check, and topic mode searches related events across the platform. It also gives example slugs and seed questions, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket markets) and the action (finding arbitrage), using precise verbs and context. While it doesn't explicitly differentiate from all siblings, it mentions polymarket_fill_risk for custom sizing, providing differentiation.

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

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

The description gives explicit usage guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It explains when to use each mode and provides examples. It also warns when not to trade: 'realizable_edge_pp ≤ 0 means... do not trade it.' This is excellent.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial transparency: explains the five model families with technical details (e.g., 'crypto_price (lognormal barrier from 90d FRED log-returns)'), caching ('Cached 1h at the KV level'), response structure with diagnostics, and a 24h-move warning about edge being priced in. It far exceeds what annotations provide.

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

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

The description is long but well-structured: it opens with a clear purpose, then breaks down segments, response top-level, and diagnostics. Every sentence adds value, but the length may reduce quick readability for an AI agent. It is front-loaded with the core purpose, earning a 4.

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 (five model families, 9 parameters, no output schema), the description is comprehensive. It explains the response structure (by_segment, fed_candidates, diagnostics), caching, and edge cases like Fed bets and filter_skips. The sibling tools are differentiated by the focus on top markets and Pipeworx disagreement.

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 explaining parameter rationale and edge cases: e.g., slippage_pp clarifies Polymarket fees and suggests adjustments, min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs, and min_edge_pp is described as 'net of slippage'. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific verb 'scan', the resource 'Polymarket markets', and its unique value proposition. The description also distinguishes it from siblings like polymarket_arbitrage by focusing on edge detection with multiple model families.

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: 'Built for "what should I bet on today"' and explains that agents discover opportunities without paging hundreds of markets. It details tradeable-edge knobs (min_liquidity, max_spread_pp) and notes that Fed bets are excluded with reasoning. However, it lacks explicit when-not-to-use instructions or direct alternatives, just barely missing a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial context: data comes from daily snapshots, decay is computed from daily closes of edge_pp_net (net of default slippage), and history depth is bounded by TTL. 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 front-loaded with the core question and provides rich detail. However, it is somewhat dense and could benefit from bullet points or clearer sectioning. Every sentence adds value, but structure could be improved.

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

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

Despite no output schema, the description fully details the response structure (tracked, expired, snapshot_dates) and explains key fields like first_seen, trend, decay_pp_per_day, lifespan_days. It also covers limitations (60-day TTL, daily closes). Comprehensive for a telemetry 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 3. The description adds meaning by specifying lookback default and clamp (2-30), and explains 'window' as snapshot family with examples. This adds value 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 it provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical persistence rather than current edges.

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

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

The description explains when to use this tool (to differentiate fresh vs. aged edges) and includes limits (60-day TTL, daily closes). However, it does not explicitly state when not to use it or list direct 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 mark as read-only, open-world, idempotent, and non-destructive. The description adds rich behavioral context: walks ladder, returns verdicts like clean/degraded/cannot_fill, and warns about stranded legs in basket mode. No contradictions.

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

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

The description is comprehensive but slightly verbose. It is well-organized with labeled sections (SINGLE-MARKET, BASKET) and a clear call-to-action. Every sentence adds value, but could be tightened slightly.

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

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

No output schema exists, but the description details all return fields and their meanings for both modes. Covers edge cases like thin_legs and forced_directional_risk, making it complete for an agent to understand outcomes.

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, so baseline is 3. The description adds meaning by explaining default values, clamps (10–1,000,000), and mode-specific behavior for side, market, and event. Adds value beyond schema.

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

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

The description clearly states the tool's function as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes and specifies return fields, making the purpose unambiguous.

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

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

Explicitly tells when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Highlights consequences of not using it (partial fills converting arb into unhedged directional positions).

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial behavioral details: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the condition for when spreads are real vs meaningless. 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 thorough but verbose. It includes many details that are necessary for correct use, but could be more concise. Structure is clear (TWO MODES, RESPONSE, SAFETY FIELDS), but length reduces 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?

Despite no output schema, the description comprehensively explains the response (spread per venue, top_spreads_pp, safety fields). It covers temporal alignment, matching logic, and edge cases. An agent has sufficient information to decide when to use and interpret results.

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

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

Schema coverage is 100% and each parameter has a description. The description adds context beyond the schema (e.g., topic list, override behavior of explicit tickers). This adds value, earning a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket. It distinguishes from siblings like polymarket_arbitrage by focusing on the same question across venues, and provides specific verb ('shows spread') and resource. The two modes (topic shortcuts and explicit tickers) are well explained.

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

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

The description explains two modes and when to use each (pre-mapped topics vs explicit pairing), and warns that most pre-mapped topics are not tradeable. However, it does not explicitly compare to sibling tools like polymarket_arbitrage, leaving the agent to infer the context.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds scoping (by identifier) and listing behavior when key omitted. 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?

Two sentences, front-loaded with action, no wasted words. 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?

Covers purpose, usage, scoping, pairing with sibling tools. No missing critical info for a simple retrieval 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 fully covers the single parameter with description. Description restates but doesn't add new semantic detail.

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 specifies the verb 'retrieve' (or 'list') and resource 'value previously saved'/'keys'. Distinguishes from siblings by mentioning '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?

Explicit use case: 'look up context the agent stored earlier'. Mentions alternatives ('remember' to save, 'forget' to delete). Could add 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 declare readOnlyHint=true and destructiveHint=false, but the description says setting mark_read:true flags events as read, which modifies state. This contradiction reduces transparency. The description does add useful context about polling and alternative endpoints, but the contradiction is significant.

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: first sentence states purpose, then details fields, filter options, mark_read explanation, and alternative access. Each sentence adds value, though it is slightly longer than minimal.

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

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

Despite no output schema, the description explains return values (source, citation_uri, raw payload) and covers all parameters and side effects. It is complete for a tool with 5 optional parameters.

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

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

Schema coverage is 100%, but the description adds value by explaining the effect of mark_read, the use of type and since filters, and the distinction of unread_only. This enriches understanding beyond the schema's basic 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 returns recent alerts from the subscription feed, listing key fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on reading existing events.

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

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

The description mentions polling works fine and that the same feed is available via a GET endpoint for scripts, implying this tool is for interactive use. It lacks explicit instructions on when not to use it versus alternatives, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds significant behavioral context: fan-out to multiple APIs, fallback logic, soft-fail for USPTO, and structured return format with URIs. No contradictions.

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

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

Description is front-loaded with example queries and provides comprehensive details, but is somewhat lengthy. However, every sentence serves a purpose 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?

Despite no output schema, description explains return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). Covers required parameters, fallbacks, and alternatives completely.

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. Description adds examples for 'since' (ISO date and relative shorthand like '7d', '30d', '3m', '1y'), clarifies 'value' accepts ticker or CIK, and notes 'type' currently only supports 'company'. This adds value beyond schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from sibling tool 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 offers explicit usage guidance: when to use (queries like 'what's new with X'), when to use entity_profile instead, and explains fallback behavior (GDELT preferred, GNews on rate limit/5xx).

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 useful context beyond annotations: key-value pair scoped by identifier, persistent vs 24-hour retention, and pairing with recall/forget. Annotations already indicate mutability (readOnlyHint=false) and idempotency (idempotentHint=true), but the description could have clarified overwrite behavior (e.g., if the same key is set again, it replaces the value). Otherwise, it provides good behavioral transparency.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds essential information. No wasted words—very 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?

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description covers all necessary context: what it does, when to use, behavioral details (scope, persistence), and how it relates to sibling tools. It is complete for an agent to understand and use correctly.

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

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

Schema coverage is 100% and schema descriptions are clear, so baseline is 3. The description adds value by providing concrete examples of keys (subject_property, target_ticker, user_preference) and stating that values can be 'any text', which helps the agent choose appropriate 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?

Clearly states the verb 'save', the resource 'data the agent will need to reuse later', and distinguishes from siblings like recall and forget. The description is specific about the action and the scope (across conversations or sessions), making it easy for an agent to understand the tool's purpose.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and provides paired tools for retrieval ('recall') and deletion ('forget'). Also explains the difference based on authentication (persistent vs 24-hour retention), giving clear guidance on context and alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description discloses internal cascading through multiple endpoints, auto-disambiguation for companies, and exact return fields for each type including citation URIs. No contradictions with annotations.

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

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

Front-loaded with user-friendly examples followed by structured enumeration of supported types and outputs. Every sentence serves a purpose; no fluff or 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?

No output schema exists, so description fully explains return values per type including citation URIs. Covers all needed details for an agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100%, but description enriches by explaining acceptable input formats per type (ticker, CIK, name for company; brand/generic for drug) with examples, and notes auto-disambiguation. Adds significant meaning 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 explicitly states the tool resolves names to canonical identifiers, gives concrete examples of questions it answers, and lists supported entity types with clear differentiation from siblings via 'Use FIRST whenever you have a name but need an ID.'

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

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

Provides clear guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and explains that it replaces 2-3 manual lookups, implying it is a primary lookup step. Lacks explicit when-not-to-use or exclusion cases, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds significant context: it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density per entity. This explains exactly what happens beyond the annotation hints.

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

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

Two sentences plus a parenthetical example are all that's needed. The first sentence states the core verb and resource, the second adds usage context. No redundant or extraneous text.

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

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

For a tool without an output schema, the description covers purpose, mechanism (probes via ai_visibility_check), return format (ranked list with score, confidence, signal density), and use case. It could briefly mention the expected number of entities (2-8) but that is already in the schema. Overall, complete given the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that the first entity in the 'entities' array is treated as the 'subject' for narrative, rest as competitors. This clarifies parameter behavior 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 uses a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison), making its unique purpose unmistakable.

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: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies the tool is for side-by-side comparison, contrasting with single-entity probes. However, it does not explicitly list when not to use or mention alternative tools for exclusion.

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 it safe (readOnly), idempotent, and non-destructive. Description adds significant behavioral context: fans out to two services, returns a detailed summary block, per-advisory details, links, alternative versions, and mentions that bundlephobia's first measurement can take 5-30 seconds and that sources_failed lists timeouts.

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 but well-organized; it front-loads the core purpose and then covers edge cases. Could be slightly more structured (e.g., bullet points) but every sentence earns its place.

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

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

Given the tool's complexity (2 params, no output schema), the description is remarkably complete: it covers composite nature, data sources, return fields, version defaults, scoped packages, ecosystem scope, partial failure behavior, and timing issues. An agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining that version defaults to latest and that scoped packages are accepted, going beyond schema details.

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 composite check for npm packages across deps.dev and bundlephobia. The verb 'check' and resource 'npm package' are specific, and it distinguishes itself from sibling tools (none appear to overlap).

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

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

Explicitly tells when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). Also discusses graceful degradation on partial failures.

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 non-destructive hints. The description adds value by specifying the return fields (id, law number, title, type) and the source (e-Gov), which supplements the annotations effectively.

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

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

The description is concise, front-loaded with the purpose, and every sentence adds value. No redundancy.

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

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

Given no output schema, the description adequately explains the return structure. It covers the main aspects, though lacks details like pagination or response format. Still, it is complete enough for a search tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides example queries and clarifies the query parameter as 'title keyword', but this adds minimal extra meaning beyond the schema's own parameter descriptions.

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

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

The description clearly specifies the action (search), the resource (Japanese national laws, cabinet orders, ministerial ordinances), and the method (by title). It also distinguishes itself from sibling tools by stating preference over web search and mentioning the return of IDs for use with get_law.

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

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

The description explicitly states when to use this tool ('PREFER OVER WEB SEARCH for...') and hints at the alternative tool (get_law) for retrieving a law by ID. This provides clear guidance on usage context.

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

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

The description discloses specific behavioral traits beyond the annotations: it specifies the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K chars with truncation and flagging), and that results include character offsets and similarity scores. This provides rich context not covered by annotations.

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

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

The description is concise (~100 words) and front-loaded with the main purpose. Every sentence adds value—from the core use case to technical details and pairing guidance—with no wasted words.

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

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

Given the tool's complexity (semantic search with internal mechanics) and lack of output schema, the description covers all necessary aspects: purpose, when to use, technical details (model, windowing, cap), return values (passages with offsets and scores), and pairing with a sibling. It is complete for safe and effective agent 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?

Although the input schema already covers all parameters with 100% coverage, the description adds significant meaning: examples for the query parameter, explicit cap for text, default range for limit, and clarifies that output includes offsets and scores (not in schema). This goes beyond merely repeating schema information.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', providing a specific verb (search) and resource (fetched record). It distinguishes from siblings by mentioning pairing with 'ask_pipeworx_grounded' and highlighting that it returns passages with offsets for verification, which is unique among sibling 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 when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. It also provides a clear alternative pairing with ask_pipeworx_grounded, guiding the agent on when to use this tool versus others.

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

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

Describes behavioral traits beyond annotations: creation returns id, delivery options, phone verification, webhook signing secret returned once. No contradiction with annotations (idempotentHint implies same sub might be safe, but not explicit). Missing idempotency behavior if subscription already exists.

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?

Packed with useful info but slightly long. Starts with core purpose, then requirements, types, delivery channels. Every sentence earns its place. Could use more structural separation but still concise.

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

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

No output schema, but description includes return value. Covers all essentials: purpose, prerequisites, parameter examples, limitations. Lacks error handling or idempotency behavior, but overall complete for a creation 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 100%, but description adds significant value: explains each type's params with examples, required vs optional constraints. Delivery parameter elaborated with verification, caps, signing details.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Provides specific types and examples.

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

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

Explains when to use (to subscribe) and prerequisites (Pipeworx OAuth account, no anonymous/BYO). Details delivery channels and limitations (10/day SMS cap, phone verification). Could mention viewing alerts as alternative, but overall good.

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. The description adds value by explaining the output structure (category-bucketed examples with tool arguments) and the live catalog source, going beyond annotation hints 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 relatively long but front-loads alternative trigger phrases, then covers purpose, output, and usage efficiently. Every sentence is informative and well-organized, though slightly verbose for the simplicity of the 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 no output schema, the description fully explains what is returned: category-bucketed example questions with exact tool+argument shapes. It covers purpose, usage, parameters, and outcome, making it complete for a simple onboarding tool.

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

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

Schema coverage is 100% for the single optional parameter. The description supplements schema by explaining that passing a topic focuses results and listing example topics, adding useful context beyond the schema's minimal description.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions as an onboarding entry point. It specifies the resource (example questions with tool+argument shapes) and explicitly distinguishes this tool from sibling meta-tools like ask_pipeworx and entity_profile, which are meant for subsequent use.

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

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

Explicit instructions: use first when unfamiliar with Pipeworx, call with no arguments for full spread or with topic for focus. It mentions alternatives implicitly (meta-tools) but does not exhaustively list when not to use it, though the context is clear enough.

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=false, destructiveHint=false, idempotentHint=true), the description adds that the row is deactivated not deleted, preserving historical events, and that ownership is enforced. No contradiction with annotations.

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

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

Two sentences with no fluff: first sentence states the action and constraint, second explains the deactivation behavior. Efficient and front-loaded.

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

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

With one parameter, no output schema, and clear annotations, the description covers all essential aspects: action, ownership constraint, and data behavior, making it complete for an agent.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The description adds that the id is returned by 'subscribe', providing useful context beyond the schema.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription' by id, and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and deactivation behavior.

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

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

The description provides specific usage context: ownership is enforced, so only own subscriptions can be cancelled. It does not explicitly mention when not to use or alternatives, but the sibling list implies alternatives for listing or subscribing.

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 behavior. The description adds valuable behavioral context: the use of SEC EDGAR + XBRL sources, the return of structured verdict types, actual values with pipeworx:// citations, percent delta, and that it condenses multiple sequential calls. 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 long but front-loads with query examples and immediately states the core purpose. Every sentence adds value, though it could be slightly tighter. Structure is logical: examples, purpose, domain, return types, efficiency note.

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 low parameter count (1), full schema coverage, and absence of an output schema, the description comprehensively covers input format, domain scope, and expected output structure (verdict types, citation, delta). It is complete for the tool's complexity and purpose.

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

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

The single parameter 'claim' has 100% schema description coverage, but the description enhances it with concrete examples like 'Apple's FY2024 revenue was $400 billion' and clarifies the natural-language expectation. This adds meaning beyond the schema's basic type definition.

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

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

The description opens with multiple natural-language query examples ('Is it true that…', 'fact check', 'verify the claim that…'), clearly specifies the tool's purpose as claim verification against authoritative sources, and limits its domain to company-financial claims for public US companies via SEC EDGAR and XBRL. It lists the verdict types (confirmed, refuted, etc.) and distinguishes itself from sibling tools that handle broader research or entity profiles.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and notes it replaces 4-6 sequential calls. While it gives clear context for when to use, it does not explicitly mention when not to use or name specific alternatives among siblings. The domain restriction to financial claims implies exclusions, but direct guidance is absent.

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