Dropbox

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context about the free Workers AI model, the cost implication of providing an Anthropic API key ('you pay Anthropic directly'), and the per-model return structure. This goes beyond annotation-provided safety info, earning a 4.

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: opening states the core function, middle explains default and paid options, closing lists use cases and return shape. Every sentence carries distinct information with no filler, making it both concise and well-structured.

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

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

Despite no output schema, the description discloses the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers cost, defaults, and use cases. Minor gap: no mention of potential rate limits or failure modes, but overall it is sufficiently complete for a read-only probe tool with 4 simple 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 description coverage is 100% (all 4 parameters documented), so baseline is 3. The description adds extra meaning by explaining that _apiKey is 'Passed straight through to api.anthropic.com' and that 'context' helps disambiguate common names. It also clarifies the relationship between models and _apiKey, which is not fully explicit in the schema.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs') and states the measurable outcome ('score visibility (0-100) per model'). It clearly distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on AI visibility scoring rather than answering questions or doing general research.

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

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

The description gives clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the free default versus paid Anthropic probing. However, it does not explicitly state when not to use the tool or mention alternatives, so it falls short of 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool works on every tier, is a single fast call, returns structured answers with stable pipeworx:// citation URIs, and routes to live news for breaking topics. No contradictions exist.

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

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

The description is long but front-loaded with the key preference statement and use cases. It includes examples and sibling guidance. A minor deduction for slightly verbose middle section that could be tightened, but overall well-structured for an important default tool.

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

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

Given the tool's complexity (6 parameters with 100% schema coverage, no output schema, and many siblings), the description fully addresses purpose, when to use, when to step up, data sources, citation format, and execution characteristics (one fast call, works on all tiers). No gaps are apparent.

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%, meaning the schema already documents all parameters (including aliases for 'question'). The description adds no additional parameter-level meaning beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description states that this tool handles factual queries requiring structured data from authoritative sources, with a specific verb ('routes the question') and resource (5,563 tools across 1462 verified sources). It clearly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for a wide range of factual queries, lists concrete trigger phrases ('what is', 'look up'), provides examples, and specifies when to step up to sibling tools (e.g., for hallucination-resistant answers use ask_pipeworx_grounded, for broad queries use deep_research). It also mentions that ask_pipeworx should be the default entry point.

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, providing a clear safety and idempotency profile. The description adds critical behavioral context beyond annotations: this is a full working router (not a fallback), has candidate routing that may be active, and currently matches ask_pipeworx exactly. 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 concise with two substantial sentences plus a clarifying follow-up. It front-loads the core identity (beta, universal router) and immediately addresses the key difference from the stable version. Every sentence adds value 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 complexity of the tool (universal router with 5,563 tools), the existence of a sibling (ask_pipeworx), full schema coverage, and rich annotations, the description is complete. It explains the experimental nature, current state, how to use it, and how it relates to the stable version. No output schema exists, but the description clarifies the response shape is identical to ask_pipeworx, so the agent can infer it.

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

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

Schema coverage is 100%, so the schema already describes all 6 parameters and their aliases. The description adds no extra parameter-level semantics, noting only that the tool accepts the same arguments as ask_pipeworx. With full schema coverage, 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 explicitly states this is the beta version of ask_pipeworx, a universal router with the same tool set and arguments. It clearly distinguishes itself from its sibling ask_pipeworx by describing its experimental edge and candidate routing improvements, making the purpose and differentiation very clear.

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

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

The description gives explicit usage guidance: use this tool when you want the newest routing, and that it functions identically to ask_pipeworx when no candidate is active. It also explains that results are compared to the stable router, helping the agent decide when to use this over its 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, openWorldHint, idempotentHint, and destructiveHint as false, so the bar is lower. The description adds valuable behavioral context: the refusal mechanism with explicit reasons like not_in_source, no_tool_match, etc., and the return format. However, it doesn't fully detail all the refusal reasons (e.g., 'data_truncated' implies truncation behavior but isn't explained). Still, this is high-value disclosure beyond annotations.

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

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

The description is front-loaded with the key purpose ('Hallucination-resistant answer mode for high-stakes reads'), followed by process details and usage guidance. It is efficient but slightly dense; every sentence earns its place. Could be slightly tighter, but overall 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 complexity (routing across 5,563 tools), the rich annotations, and that there is no output schema, the description is remarkably complete. It explains the routing mechanism, the extraction process, the return format (with refusal reasons), and when to use it. The only minor gap is that details about 'data_truncated' are not fully expanded, but that is a fractional trade-off.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any parameter-level detail beyond what the schema already provides (e.g., aliases like q, text, input are already described in the schema). The description focuses on the behavior, not on parameter 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?

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads.' It specifies the verb ('extracts the answer') and the resource ('tool result'), and distinguishes it from its sibling ask_pipeworx by emphasizing the grounded, evidence-based 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 explicitly tells when to use this tool ('high-stakes reads...when an answer will be quoted, cited, or acted on') and when not to use it ('prefer ask_pipeworx for casual lookups'). It also explains the cost trade-off ('costs one extra LLM call'), providing clear guidance for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes well beyond by disclosing short-circuit behavior for low-confidence matches, closed-market handling, wide-spread tradeability warnings, news fallback mechanisms on GDELT 429s, and cancellation-rule risk parsing. This level of behavioral detail 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 extremely dense and well-organized with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). It is front-loaded with purpose and usage, and every detail earns its place for a tool this complex. Slight verbosity is acceptable, but it could be tightened without losing 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?

With no output schema, the description carries full responsibility for return values and edge cases. It thoroughly documents the response shapes, resolver match confidence and alternatives, parent-event extraction for partition legs, news fallback fields, and blocking statuses. It also covers practical risks like cancellation rules and spread illiquidity. Complete for a highly 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%, and the description adds substantive meaning: market accepts slug, URL, or question text; depth explains quick vs thorough fan-out and default; include_raw details response size trade-offs and when to use raw payloads. Examples further illustrate concrete valid inputs. The description enriches every parameter 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 opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings by being an all-in-one research tool that resolves the market, classifies the bet, and fans out to category-specific data packs. It also specifies accepted input formats (slug, URL, question text), leaving no ambiguity about what the tool does.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and numerous fan-out examples that illustrate when to invoke it. It does not explicitly name alternative tools or state when not to use this tool, but the rich examples and clear context give strong guidance. Missing explicit when-not/alternatives references prevents 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 readOnly, idempotent, and non-destructive. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction 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?

The description is dense but well-structured: trigger phrases first, then purpose, then data details. Every sentence provides unique value; the trigger list is slightly long but helps recognition. No filler 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, but the description mentions 'paired data + pipeworx:// citation URIs per entity', explains data sources and constraints, and covers key behaviors. Combined with annotations and detailed parameter descriptions, it is fully contextual for the agent.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning with concrete examples ('AAPL','MSFT'), per-type data fields, and behavior like sorting. It goes beyond simple enum/array descriptions to explain what each type actually retrieves.

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 performs side-by-side comparison of 2-5 companies or drugs in one call, with explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from single-entity lookups by emphasizing parallel comparison and 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

It provides explicit when-to-use guidance with trigger phrases and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. It also constrains to 2-5 entities, implying not for single-entity queries, but does not explicitly name a specific alternative sibling tool.

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

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

Details the research process (decomposition, parallel routing, findings packet with gaps, contradictions, hop field, citation_uri), explains semantic excerpting of large records, timing estimates (15-90s), and the fact that citations are fetchable via pipeworx:// URIs. Complements annotations (readOnlyHint, openWorldHint, idempotentHint) with actionable behavioral context.

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

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

The description is thorough but somewhat verbose; it could be more concise while retaining critical details. However, it front-loads essential usage constraints and is well-structured with clear functional sections.

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 output schema, the description comprehensively explains the findings packet content, depth behaviors, timing, limitations (empty gaps, not open-web search), citation resolvability, and edge cases like semantic excerpting. Covers all aspects needed for an agent to use the tool correctly.

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

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

Both question and depth parameters have schema descriptions (100% coverage). The description adds significant value: explains depth enum meanings (quick=3 facets single hop, standard=5 with gap-recovery+contradictions, thorough=8 paid with iterative hop), and elaborates on the question parameter's multi-part suitability.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, decomposes questions into facets, routes to tools in parallel, and returns a findings packet. It explicitly distinguishes from siblings: for single lookups use ask_pipeworx, for breaking news use 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?

Provides explicit guidance on when to use this tool vs alternatives: requires free account (paid for 'thorough'), fallback tool for unsigned users, recommends ask_pipeworx for single queries or current news. Also explains depth levels and when to choose each, and warns about empty gaps for non-catalog topics.

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 signal read-only, idempotent, and non-destructive behavior. The description adds valuable context about output: returns top-N tools with names, descriptions, and full schemas, and that results are ready to call directly with no second schema lookup, which goes beyond annotations.

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

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

The description is concise at four sentences, front-loaded with the main verb, and each sentence contributes: purpose, usage, output, and when to call. The domain list is long but directly informs the agent of the tool's scope, so it is not wasteful.

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 discovery tool with no output schema, the description explains what it returns and why it is useful. It covers usage context and scope, making it complete enough for an agent to decide when to invoke it. It does not need to detail sibling comparisons.

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 of query and aliases. The description adds no additional parameter information, but since the schema fully documents all six parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It identifies specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-tool for discovering other tools rather than performing domain-specific tasks.

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?

Usage guidance is explicit: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when not to use it ('not just one answer'), implying direct tool use for specific single answers.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds the useful fact that it 'Returns folder metadata,' but does not disclose other behavioral details such as error handling when the path exists or permission requirements. Since annotations cover the safety profile, this is acceptable but not exceptional.

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 long, front-loads the core action, and every word adds value. It is concise and well-structured, with no filler or repetition.

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

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

For a simple 2-parameter tool with a rich schema and annotations, the description is mostly complete. It states the return value ('Returns folder metadata') and the purpose. It does not mention edge cases like existing paths or permission requirements, but these are not critical given the simplicity and the presence of an output schema. Minor gap but not significant.

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

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

Schema description coverage is 100%, and the input schema already documents both parameters (path and autorename) with clear descriptions. The description only echoes 'at a specified path,' which adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Create a new folder in Dropbox at a specified path') and identifies the resource (Dropbox folder). It distinguishes itself from sibling tools like dropbox_download, dropbox_get_metadata, and dropbox_list_folder by using the verb 'Create', which is unique among the Dropbox-related siblings.

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

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

The description provides clear usage context: 'Use to organize files or set up directory structures.' It does not explicitly name alternative tools or when-not conditions, but the intended use case is obvious. This is a step below the highest bar because no exclusions or alternative tools are mentioned.

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

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

Annotations already declare readOnly, non-destructive, and idempotent behavior. The description adds the return format (content as text plus metadata), which is useful for setting expectations. It does not contradict annotations and supplements them with functional output 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 two short sentences that state purpose and use case directly, with no unnecessary words or repetition.

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

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

Given the tool's simple one-parameter interface, the presence of an output schema, and the clear description of what the tool returns, the description provides sufficient context for an agent to select and invoke the tool correctly.

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

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

The input schema fully documents the only parameter, 'path', as 'File path to download'. The description does not add further syntax or format details; thus the schema carries the semantic load, so baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Download') and resource ('file from Dropbox'), and distinguishes itself from sibling tools by specifying the return of content plus metadata (size, type, modified date). This makes the tool's 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?

It explicitly states when to use the tool: 'Use to retrieve file contents for processing or inspection.' While it does not enumerate alternative tools, the context implies a clear use case that differs from metadata-only tools like dropbox_get_metadata or listing via dropbox_list_folder.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the metadata fields returned and the recommendation to use it before modifying, but this is more about output scope than behavioral caveats. No additional constraints, permissions, or failure modes are disclosed, so a 3 is appropriate given the annotation coverage.

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

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

Two sentences, front-loaded with the action and resource, and every clause carries useful information. The metadata list is concise and the usage tip is brief. No filler or repetition.

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

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

For a simple one-parameter tool with a rich output schema (metadata fields are already listed) and comprehensive annotations (safe read-only, idempotent), the description fully covers purpose, usage context, and return contents. No missing information that would impair an agent's ability to invoke the tool.

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

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

The schema has 100% coverage: the only parameter 'path' is described as 'File or folder path'. The description reiterates that the tool works for files and folders but does not add extra meaning about path format, leading slashes, or special values. Baseline 3 is correct when the schema fully documents the parameter.

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

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

The description uses the specific verb 'Get' with a clear resource ('detailed metadata for a file or folder') and enumerates the metadata fields (size, modified date, ID, sharing status, revision info). This distinguishes it from sibling tools like dropbox_download or dropbox_list_folder, 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 states when to use the tool: 'Use before downloading or modifying to inspect properties.' This provides clear usage context and implies it is a pre-action inspection step. It does not explicitly name alternative tools for other scenarios, but the guidance is sufficient for the intended use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description doesn't need to restate safety. It adds useful behavioral context by noting the return fields (names, types, sizes, modification dates) and the directory-listing concept, though it doesn't disclose pagination or recursion behavior. 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 two sentences, front-loaded with the core function, and contains no redundant or irrelevant information. Every word earns its place.

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

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

For a simple listing tool with only two parameters, an output schema, and complete safety annotations, the description covers the essential purpose and use case. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

The input schema covers both parameters with 100% description coverage, so the schema handles the semantic burden. The description adds minimal extra meaning beyond confirming the path concept and listing use case, which is already implied by the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists files and folders in a Dropbox directory, with a specific verb and resource. It distinguishes itself from sibling tools like dropbox_create_folder and dropbox_download by focusing on listing, and specifies the returned metadata (names, types, sizes, modification dates).

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 when browsing folder contents or checking what's stored at a path.' It provides clear context for the intended use case, though it does not explicitly mention when to prefer alternatives like dropbox_search or dropbox_get_metadata.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context about return values ('matching paths, file types, and metadata') and search capabilities ('by name or content'). It does not mention pagination or rate limits, but the annotation coverage lowers the burden.

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 concise sentences with no filler. Each sentence earns its place: the first states the action, the second summarizes return data, and the third gives a usage context. It is front-loaded and easy to scan.

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?

This is a simple 2-parameter search tool with an output schema (noted in context signals), so the description does not need to explain return values in depth. Annotations cover safety, and the description provides clear usage context. The tool is well-specified for an agent to select 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?

Schema coverage is 100% for both parameters (query and max_results). The description adds the semantic nuance that the query searches 'by name or content', but this is already somewhat inferable from the schema and does not add significant new meaning beyond the 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 states the verb ('Search'), resource ('Dropbox'), and scope ('files and folders by name or content'). It distinguishes the tool from sibling Dropbox tools such as dropbox_create_folder, dropbox_download, and dropbox_list_folder by focusing on search functionality.

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

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

The description explicitly tells when to use the tool ('when you need to find a file without knowing its exact location'). It does not name alternatives directly, but the context is clear enough to differentiate from other Dropbox operations. Lacks explicit exclusions or comparison to search_within, so not 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 readOnly, openWorld, idempotent, non-destructive behavior. The description adds valuable context beyond that: it explains the multi-source fan-out (SEC EDGAR, XBRL, USPTO, news, GLEIF), details the exact return fields, and discloses a soft-fail limitation ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated') and a fallback chain ('GDELT→GNews'). 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 long but information-dense. It front-loads natural-language triggers, then gives a strong preference statement, and systematically lists output fields and limitations. Every sentence contributes essential operational knowledge; however, it could be slightly trimmed by removing redundant example phrasings. Still, the structure is effective 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?

For a tool with only two simple parameters and no output schema, the description is remarkably complete: it specifies input formats, unsupported inputs, fallback behavior, expected outputs with URIs, and its relationship to sibling tools. The agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%: both 'type' and 'value' already have detailed descriptions including the enum restriction and the zero-padded CIK format example. The description repeats this information without adding further semantic nuance, so it adds no value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the exact verb ('profile'), resource ('US public company'), and scope ('cross-source'), and distinguishes it from sibling tools like resolve_entity and deep_research by positioning it as the preferred option for holistic company 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?

Provides explicit usage cues with example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and a clear preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an exclusion: 'names not supported (use resolve_entity first if you only have a name).' This fully addresses when to use and when not to use the tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat those. The description adds that the memory was 'previously stored,' implying it only affects existing entries, but it does not disclose what happens on missing keys or whether deletion is reversible. Given the annotations cover the key safety profile, this is adequate but not rich.

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 concise sentences. The first sentence states the core action, and the second gives usage rationale and related tools. Every word earns its place, with no redundancy or filler, and the structure is front-loaded with the primary purpose.

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

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

Given the tool's simplicity—one parameter, no output schema, and clear annotations—the description is nearly complete. It explains what, when, and how to use it, and references sibling tools. It omits edge-case behavior like non-existent keys or error handling, but the idempotent hint mitigates the need, making this a solid 4.

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

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

The schema has 100% parameter description coverage, with the key property described as 'Memory key to delete.' The tool description essentially restates this without adding format, case-sensitivity, or example syntax. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no meaningful semantic value beyond that.

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 'Delete a previously stored memory by key,' which is a specific verb+resource combination that clearly states the tool's function. It distinguishes itself from sibling tools by explicitly naming remember and recall as complementary operations, making its role in the memory system clear.

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

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

The description provides explicit conditions for use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' This clearly indicates when the tool is appropriate. It also mentions pairing with remember and recall, though it does not specify when not to use it or name direct alternatives, so it falls just short of 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown, which is useful beyond the annotations.

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

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

The description is three sentences, with the primary purpose front-loaded in the first sentence. Each sentence contributes meaningful information (functionality, output format, use cases), though it could be slightly more concise without losing 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?

With a simple 2-parameter schema and no output schema, the description adequately explains the return format ('single text blob') and where to place it (site-root/llms.txt). It also covers use cases, making it sufficiently complete for an agent to understand the tool's purpose and output.

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% for both parameters (url and max_links). The description does not add additional parameter details beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb (generate) and resource (llms.txt file) and explains the output. It distinguishes this tool from siblings like scan_competitor_ai_presence by focusing on creating a standard llms.txt file rather than broader AI visibility analysis.

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 ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing...'), giving clear context for when to use it. It lacks explicit alternative comparisons or exclusions, but the use cases are specific 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful behavioral details: it lists only active subscriptions (unless include_inactive is true) and specifies the exact fields returned, which goes beyond what annotations provide.

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

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

Three short sentences, each adding value: the first states the core purpose, the second lists return fields, and the third gives usage guidance. No filler or redundant information.

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

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

The tool is simple with a single optional parameter and no output schema. The description covers the purpose, return fields, and when to use it. The parameter is fully documented in the schema, so there are no significant gaps.

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

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

The only parameter, include_inactive, has a full description in the input schema (100% coverage). The description does not mention it, but the schema fully explains it, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the caller's active subscriptions.' It also enumerates the return fields, which reinforces the purpose. It clearly distinguishes itself from sibling tools like subscribe and unsubscribe by being a read-only listing operation.

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

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

The description gives explicit usage context: use this to review what you're monitoring before adding more subscriptions, or to find an id to cancel. It does not name specific alternative tools or state when not to use it, but the guidance is clear and actionable.

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

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

Annotations are all false (readOnly, openWorld, idempotent, destructive), so they provide little safety/behavioral context. The description compensates with several non-obvious behaviors: returns a claim_token when filing without an account, allows later lookup via passing that token as the only argument, is rate-limited to 5 per identifier per day, is free, and doesn't count against tool-call quota. It also clarifies the team reads digests daily. Minor gap: doesn't state whether filed feedback can be edited/deleted, but the disclosed details go well beyond the annotations.

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

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

The description is well-structured and front-loaded with the core intent, then systematically covers scope, anti-guidance, account flow, and operational details. It's longer than ideal for a simple tool, but every sentence earns its place: the exclusion of other MCP servers is critical to prevent misrouting, and the rate limit/quota details are non-obvious. The only minor waste is the 'Not sure?' sentence, which somewhat restates the identification guidance given just before.

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 feedback tool with no output schema, the description provides comprehensive contextual coverage: what types of feedback are accepted, which servers' tools are in scope, how to identify them, the claim_token flow for following up, rate limits, cost, SLAs (daily digest), and roadmap impact. The parameter semantics are fully covered by the schema plus description, and the lack of an output schema is compensated by explaining what returns to expect (claim_token, status, changes). This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context beyond the schema: clarifies the 'other' enum value meaning, explains the claim_token parameter's two-phase usage pattern (file then read), and ties the context object to 'which tool, pack, or vertical'. It slightly loses a point because the message parameter's requirement to reference Pipeworx tools rather than pasting end-user prompts is a usage nuance that could be more prominently connected to the parameter.

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

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

The description states a clear, specific verb+resource: tell the Pipeworx team about broken/missing/needed things, with distinct types (bug, feature, data_gap, praise). It also distinguishes itself from sibling research and file tools by focusing on feedback exclusively for Pipeworx-served tools, while siblings like ask_pipeworx or deep_research serve 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 states when to use (bug, feature, data_gap, praise) and when NOT to use (issues with other MCP servers' tools), including an alternative action ('file it with that server instead'). It also gives a clear disambiguation rule based on tool names and mentions the claim_token reversal to check status, which is a usage pattern.

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 establish readOnlyHint, openWorldHint, and idempotentHint, so the bar for added context is moderate. The description adds valuable behavior disclosure: data is cached for 5min-1h depending on window, and the signal derives from CF analytics-engine with no PII. This gives agents insight into data freshness and privacy but omits specific rate limits or auth requirements, which are not critical given the safety hints.

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

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

The description is tightly written: three sentences covering purpose, use cases, and technical details without redundancy. It is front-loaded with the main claim and efficiently captures all necessary information.

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

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

For a tool with one optional parameter and no output schema, the description is sufficiently complete. It explains the return contents (top tools, packs, call volume), the windows, the caching behavior, and the privacy guarantee. An agent can confidently select and invoke this tool with minimal missing 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?

The input schema fully documents the single `window` parameter with enum values and descriptions. The tool description adds semantic nuance beyond the schema by noting that shorter windows surface what's hot right now while longer windows show steady-state demand, aiding 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 clearly states the tool's function: it returns top tools, top packs, and total call volume for what other AI agents are calling on Pipeworx. It specifies the resource (Pipeworx trending data) and the action (returns), making it immediately distinguishable from siblings like discover_tools 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 provides explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with current usage. While it doesn't name alternative tools explicitly, the use cases imply when this tool is appropriate and when other tools (like discover_tools) might be better suited.

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 (readOnlyHint, openWorldHint, etc.), the description discloses internal algorithms: the 0.30 Jaccard similarity threshold, the placeholder fraction filter, the fill check against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0 ('do not trade it'). This gives the agent essential decision-making context.

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

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

While well-structured with front-loaded purpose and clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), the description is quite long and has minor redundancy—for example, the event mode is introduced early and then re-explained in detail. It remains efficient given the tool's complexity, but slightly more editing would earn a 5.

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

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

With no output schema, the description fully specifies the response shape: opportunities[] with fields like gap_pp and suggested_trade, partition_check details, and fill-check results. It also explains edge cases (e.g., null arbs when placeholder fraction >20%). This is complete enough for an agent to use the tool correctly without external documentation.

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

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

The input schema already has descriptions for event and topic, but the tool description goes much further by providing concrete example values ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), accepting full URLs, and explaining what each mode does internally. This adds substantial semantic value beyond the structured schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique methodology and output. The three invocation modes (default, event, topic) are precisely defined with 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?

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning).' It also names an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is clear when/when-not 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?

Beyond the readOnly/idempotent annotations, the description discloses extensive behavioral traits: caching at the KV level, response structure, model family grouping, gate relaxation history, and edge-case warnings like the 24h-move alert. It even explains the per-leg Kelly nuance for partition arbs, far exceeding 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 a long, dense paragraph covering methodology, response structure, knobs, and diagnostics without any bullet points or headers. It is front-loaded with the main purpose, but the lack of formatting makes it harder to scan, even though every sentence carries useful information.

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

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

Given no output schema, the description fully compensates by detailing the response top-level (by_segment, fed_candidates, _diagnostics), model families, filter gate logic, and caching behavior. This provides an agent with complete expectations about return values and caveats, making the tool well-specified.

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, but the description goes beyond the schema by explaining the strategic purpose of key knobs (tradeable-edge filters, min_partition_leg_kelly behavior, slippage assumptions). It doesn't restate every parameter, but it enriches the most important ones significantly.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. This specific verb+resource+outcome combination distinguishes it from siblings like polymarket_arbitrage, which focuses on a different opportunity type.

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

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

The description explicitly frames the tool as 'Built for "what should I bet on today"' and provides detailed knob guidance (e.g., 'Set to 2 to require tight books') for when to adjust filters. It lacks explicit mention of alternative tools or exclusion criteria, but the usage context is clear and actionable.

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

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

Adds rich behavioral details beyond the annotations: edge_pp_net is signed (negative = SELL YES), decay is computed on absolute value, snapshots are written on cache-miss so gaps mean no scan, history depth is bounded by 60-day TTL, and decay uses daily closes not intraday. These are critical for correct interpretation and align with readOnly/idempotent hints.

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

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

The description is well-structured with clear sections (Args, RESPONSE, LIMITS) and is front-loaded with the core purpose. Although long, every sentence adds value, including the parenthetical example and detailed response semantics. The length is justified by the tool's complexity and absence of an output schema.

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

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

With no output schema, the description extensively explains the response format: tracked[] with time-series, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with cache-gap semantics. It also documents limits like TTL and daily-close basis. This is 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?

The input schema already describes both parameters fully, including defaults and clamps (100% coverage). The description repeats the defaults and adds 'max 30' but does not introduce new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as edge persistence and decay telemetry built from daily polymarket_edges snapshots, with a concrete question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges by focusing on historical time-series and decay rather than current edge values.

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 context by explaining that this tool analyzes historical snapshots and gives a specific use case (comparing fresh vs 3-week-old edges). However, it does not explicitly say when to use this tool over alternatives like polymarket_edges or other siblings, and lacks exclusion statements. Clear context without explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it walks the order book ladder, returns specific metrics like vwap_fill_price and slippage_pp, and warns that partial basket fills convert an arb into unhedged directional risk. This goes well beyond the annotations and explains real-world behavior and failure modes.

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 leads with the core purpose, then uses REQUIRES to separate modes, and each mode's behavior and outputs are listed clearly. While long, every sentence carries essential information for a complex two-mode tool. The use of capitalization and explicit labels helps navigation.

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

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

The tool has no output schema, yet the description fully enumerates the return fields for both modes (top_of_book, vwap_fill_price, etc. for single-market; theoretical_sum, capture_ratio, thin_legs, etc. for basket). It also covers edge cases like forced_directional_risk and max_clean_notional_usd, making the tool's behavior predictable without needing additional documentation.

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. However, the description enriches parameter meaning significantly: size_usd is defined as 'max spend on buys, target proceeds on sells' for single-market and as 'settlement notional S' for basket mode, and side behavior is clarified for both modes. This adds interpretive value 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource pairing that clearly states what the tool does. It distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as tools to precede, making its unique role 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?

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) and the required parameters for each, giving clear context and exclusions (e.g., no need for small trades).

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

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

Annotations already indicate readOnly/idempotent/openWorld, but the description goes far beyond by disclosing compatibility_warning conditions, temporal_alignment implications, skipped_cross_type/subtype meanings, and that aligned:false makes spreads meaningless. These behavioral details are essential and not present in any structured metadata.

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-organized with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence carries useful information. It is long, but the tool's complexity justifies the detail. A slight reduction in the final cautionary sentence could tighten it without loss.

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

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

For a tool with no output schema, the description thoroughly covers return values (leg-by-leg prices, spread in pp), key safety fields, edge cases, and behavioral limitations. It explains what to expect under different match outcomes, making the tool usable without a formal output schema.

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

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

Schema coverage is 100%, but the description adds crucial semantics beyond field names: it explains that 'topic' auto-fetches the matching event, explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side for custom pairings, and lists valid shortcut values. This enriches the parameter understanding significantly.

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

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

The description opens with a specific verb+resource+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explains two operation modes (topic shortcuts vs explicit event pairing).

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

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

It provides clear instructions on how to use the two modes, when explicit event tickers are needed, and warns that most pre-mapped topics return compatibility_warning and are not tradeable. However, it does not explicitly name alternative sibling tools or state 'use X instead of Y', so it lacks explicit exclusion 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description explains scoping to the identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior (value retrieval vs. key listing). This adds valuable behavioral context not present in annotations.

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

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

The description is three sentences, front-loading the core function, then providing usage context and scoping. Every sentence earns its place with 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 simple parameter set and absence of output schema, the description fully covers what it does, when to use it, how it is scoped, and its relation to sibling tools. No important behavioral aspect is left unexplained.

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 schema covers 100% of parameter documentation, the description enriches the key parameter by explaining the omit-to-list-all behavior and giving example keys (ticker, address). It clarifies that the key is the one used with remember, adding semantic value beyond the schema.

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

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

The description clearly states the tool retrieves a value previously saved via remember, or lists all saved keys if key is omitted. It uses specific verbs and distinguishes itself from memory-related siblings (remember, forget), making its 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?

It explicitly says 'Use to look up context the agent stored earlier' and provides concrete examples (user's target ticker, address, research notes). It also directs pairing with remember to save and forget to delete, offering clear when-to-use guidance relative 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?

The description explicitly states that setting mark_read:true 'flags returned events read' and affects subsequent calls, implying a state mutation. This directly contradicts the annotation readOnlyHint=true. Although the description adds useful return-format details, the contradiction is a serious inconsistency, warranting a 1 per the rubric. No other disclosure can mitigate this mismatch.

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 main purpose. It includes necessary examples and the alternative endpoint without excessive verbosity. It earns a 4 rather than 5 because the last sentence about the feed URL could be seen as slightly tangential for an agent using the tool, but it is still useful.

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

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

For a read-oriented tool with no output schema, the description adequately explains the return format (source, citation_uri, payload) and includes operational guidance (polling, endpoint). The lack of pagination details is minor given the schema's limit/default, and the contradiction with annotations lowers the overall completeness slightly, but the description alone is fairly comprehensive.

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 adds value beyond the schema by explaining the semantics of mark_read ('so the next call only shows newer ones') and giving an example type filter. It does not cover all params (e.g., unread_only), but the additional context for key parameters justifies a 4.

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

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

The description clearly states the tool's verb and resource: 'Pull fired events from your subscription feed.' It specifies the scope (recent alerts, persisted feed) and gives examples of filters. However, it does not explicitly differentiate from sibling tools like list_subscriptions, so it misses the 'distinguishes from siblings' bar for a 5.

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

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

The description provides clear context for use, including filtering options and the polling behavior ('Polls work fine'). It also offers an alternative for scripts/dashboards via the direct endpoint, giving the agent a decision point. However, it doesn't explicitly mention when not to use this tool or name sibling alternatives, so it falls short of 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?

Beyond the annotations (readOnlyHint=true, etc.), the description discloses fan-out to multiple sources, GDELT→GNews fallback logic, USPTO soft-fail limitation, and the output structure. This adds significant behavioral context not available from 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?

The description is dense and front-loaded with example queries, then explains sources, parameters, and output. Every sentence contributes useful information without fluff or redundancy. The length is justified by the tool's multi-source complexity.

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

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

With no output schema, the description fully covers return values (changes[], total_changes, citation URIs). It also explains the three data sources, fallback behavior, and a known limitation (USPTO sunset). The description is sufficiently complete 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%, so baseline is 3. The description adds meaningful semantics beyond schema by providing examples for 'since' (ISO or relative, with recommended '30d'/'1m'), and clarifies 'value' accepts ticker or CIK. This is extra guidance beyond the schema descriptions.

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

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

The description clearly states it provides a change feed for a company over a recent time window, with explicit example queries. It distinguishes itself from sibling entity_profile by contrasting dynamic changes versus static 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 gives concrete when-to-use examples (e.g., "What's new with X") and explicitly names an alternative: 'Use entity_profile instead when you want the static profile'. It also explains the fallback behavior between GDELT and GNews, which helps the agent decide if this tool is appropriate.

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, the description discloses persistence semantics: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. This adds critical context about retention and key scoping that annotations do not 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 four sentences with each earning its place: purpose, when-to-use, storage details, and companion tools. It is front-loaded with the primary action and contains no redundant or unexplained terms.

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

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

For a simple tool with no output schema, the description is complete: it covers purpose, usage triggers, persistence lifetime, scoping, and pairing with recall/forget. Agents have sufficient information to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for key and value, so baseline is 3. The description adds meaning by clarifying that the memory is stored as a key-value pair 'scoped by your identifier', which explains key uniqueness and namespace behavior 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 function with specific verb 'Save' and resource 'data the agent will need to reuse later'. It distinguishes itself from sibling tools by naming recall (retrieve) and forget (delete), and specifying a key-value store scoped by identifier.

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

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

Explicit usage guidance is provided: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also references alternatives by stating 'Pair with recall to retrieve later, forget to delete'.

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, so the tool is clearly a safe, non-destructive lookup. The description adds extra behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, multiple internal cascading lookups, and explicit labeling of resolved vs. unresolved identifiers. No contradictions detected.

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

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

The description is dense with valuable information but somewhat verbose in the nested explanations about company resolution. The opening few lines immediately answer the 'what is it' and 'when to use it' questions, which is good front-loading. However, the middle section on company resolution could be slightly more concise without losing meaning.

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

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

Given the two-parameter schema with 100% coverage, no output schema (so description must explain return values), and no nested objects, this description is remarkably complete. It specifies exactly what identifiers are returned for each type, how errors are handled (unresolved list, graceful degradation), and the internal cascading behavior. For a lookup tool of this complexity, an agent has everything needed to decide when to call it and what to expect back.

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

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

Schema coverage is 100% and both parameters (type, value) have descriptions in the schema. The description goes beyond schema by clarifying acceptable input formats for value (e.g., 'AAPL', '0000320193', 'ozempic'), and explains the 'company' enum in depth (cross-source identity spine, which identifiers are returned, what happens with ISINs). The 'drug' type is also enriched with RxNorm context. The only reason it's not a 5 is that some details (like exact output structure) are left for the agent to infer from the listed identifiers.

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

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

The description opens with concrete example queries and clearly states the tool's primary function: resolving user-spoken names to canonical identifiers required by other tools. It explicitly distinguishes itself from siblings like compare_entities or entity_profile which likely handle already-resolved entities rather than the name-to-ID mapping step.

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: 'Use FIRST whenever you have a name but need an ID', positioning this tool as the prerequisite before using other tools. It also lists what identifiers to expect for each entity type and even hints at when alternative lookups may be needed (e.g., ISIN-based resolution for non-US entities not covered by EDGAR).

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 the tool internally probes each entity using ai_visibility_check and returns a ranked list with score, confidence, and signal density. Aligns with the readOnly/idempotent annotations and adds context about composite behavior and output structure, though it doesn't discuss potential cost or latency.

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 and front-loaded, starting with the core action, then detailing the process, a use case, and the return value. Each sentence contributes information without redundancy.

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

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

The description explains the tool's composite behavior, its use case, and its return format, which compensates for the lack of an output schema. It provides sufficient context for an agent to decide when and how to invoke the tool, making it complete.

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

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

Schema coverage is 100% with detailed descriptions for all parameters, including the entities semantics. The description adds no new parameter-specific information beyond the schema, so per the guideline, 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 function: comparing AI visibility across multiple entities, using ai_visibility_check, ranking by score, and identifying most/least recognized. It distinguishes itself from single-entity tools like ai_visibility_check by emphasizing multi-entity comparison, and from generic compare_entities by focusing specifically on AI presence.

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

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

Provides a clear use case (competitive AI-marketing audits) with an illustrative query, implying when this tool is appropriate. However, it does not explicitly exclude alternatives or mention when to use a single-entity tool instead, earning a 4 rather than 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?

The description discloses behavioral traits beyond the annotations: it details the fan-out across external services, partial failure handling ('sources_failed will list it if it times out, the rest still returns'), and the potentially slow first measurement ('bundlephobia's first measurement on a new version can take 5-30s'). This adds valuable context beyond the readOnlyHint and idempotentHint annotations, with 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 dense but structured: purpose, usage trigger, return value breakdown, ecosystem limitations, and failure behavior are all covered in a logical order. No sentence is wasted; each adds critical information for tool selection and invocation. The length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: lists summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases (timeouts, ecosystem limitations) and clear failure semantics. The description is fully self-contained for an agent to use this tool correctly.

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

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

Both parameters (package and version) are fully described in the input schema with 100% coverage, including scoped package examples and default-to-latest behavior. The description itself does not add meaningfully to the parameter semantics; it focuses on the composite output rather than the parameters. With schema coverage at 100%, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call', clearly stating what the tool does and its scope. It distinguishes itself from siblings by naming the exact data sources (deps.dev and bundlephobia) and the composite nature, making its 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 states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusions/alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which guides the agent toward the correct tool for non-NPM ecosystems.

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, but the description adds substantial behavioral detail: BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag, and passage offsets for verbatim verification. This goes well beyond annotations and fully discloses the tool's behavior.

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

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

The description is information-dense but not bloated; each sentence contributes a distinct aspect (action, input/output, usage context, pairing alternative, technical details). It is front-loaded with the core purpose and remains organized, though slightly long, it justifies its length.

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

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

Given there is no output schema, the description fully explains return values ('passages with character offsets and similarity scores') and covers edge cases like truncation. It also integrates with sibling tools, making it complete for the tool's complexity and context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for 'text' (SEC 10-K body, article) and 'query' (supply-chain risk, revenue), plus explaining the 'top-N passages' concept that maps to the 'limit' parameter. This enriches the schema's dry 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 performs 'Semantic search INSIDE a fetched record', using a specific verb and resource. It distinguishes itself from sibling tools by emphasizing 'inside a fetched record' and explicitly pairing with ask_pipeworx_grounded, clarifying its unique role in the workflow.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt'. It also names a specific alternative workflow ('Pairs with ask_pipeworx_grounded') and explains when this tool is preferable, giving clear direction on when to use it versus other tools.

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

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

Even with annotations present, the description discloses important behavioral details beyond the boolean hints: OAuth account requirement (anonymous/BYO cannot persist), SMS verification and 10/day cap, always-on feed, webhook HMAC signing, one-time secret exposure, and auto-disable after 10 failures. No contradiction with annotations.

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

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

The description is long but well-structured, front-loaded with the core purpose and return value, then organized by supported types and delivery channels. It could be tightened by removing examples already present in the schema, but every section adds useful operational context.

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 complex tool with nested objects, no output schema, and multiple delivery modes, the description covers return value, authentication requirements, per-channel behavior, verification, rate limits, and webhook security details. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the input schema already documents all parameters, including examples for each subscription type. The description largely repeats the same parameter information rather than adding new meanings, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: "Create a proactive monitoring subscription to a live-data event stream." It also states the return value ("Returns the new subscription id"), clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description gives clear context for when to use the tool (setting up proactive monitoring) and details on supported subscription types and delivery channels. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of 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 and idempotentHint. The description adds meaningful behavioral context: results are drawn from the live catalog of thousands of tools, output is category-bucketed with tool mappings, and calling with or without topic changes scope. These details go beyond what annotations alone 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 longer than necessary, with a six-item list of example questions and a full category enumeration, but each section serves a purpose: examples aid pattern-matching, categories set expectations, and usage instructions are clear. It could be trimmed slightly without losing impact.

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

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

With no output schema, the description fully compensates by explaining what is returned (category-bucketed example questions with tool and argument shape), how to call it (no args vs topic), and when to use it. It also covers the meta-tool learning angle, making it complete for an onboarding tool.

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

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

The input schema already provides 100% coverage for `topic` with full enum list and omission guidance. The description's mention of examples ('finance', 'pharma', 'betting') and 'no arguments for the full spread' adds no new semantic info beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shape, and identifies itself as the onboarding entry point. It distinguishes from sibling tools like ask_pipeworx and entity_profile by focusing on 'what is worth asking' and teaching how to call meta-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?

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' and names alternatives (ask_pipeworx, entity_profile, compare_entities). This provides clear when-to-use and alternative 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?

The description adds meaningful context beyond the annotations by disclosing ownership enforcement and that the row is deactivated rather than deleted, which aligns with the annotative hints (readOnlyHint=false, destructiveHint=false) and explains the soft-delete semantics.

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

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

The description is concise (two sentences), front-loaded with the primary action, and every sentence adds value: ownership scoping and soft-delete behavior are both useful and non-redundant.

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 single-parameter tool, the description covers the core action, the ownership rule, and the side effect on historical events. It is sufficiently complete given the absence of an output schema and the low parameter complexity.

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

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

The input schema already provides full coverage (100%) for the single parameter 'id', including its type and origin. The description does not add additional parameter semantics beyond what the schema states.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscriptions), distinguishing it from sibling tools like subscribe and list_subscriptions. It also adds scope (ownership enforced) and behavior (deactivated not deleted).

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

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

The description implies usage (cancel a subscription by id) but does not explicitly state when to use this versus alternatives, nor does it mention list_subscriptions for viewing subscriptions. No exclusions or alternative tools are named.

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 rich behavioral context beyond annotations: it explains the two routing pipelines, defines all verdicts, and crucially differentiates 'could_not_verify' (check did not happen) from 'unsupported' (no source exists). It also discloses error payload structure. This goes well beyond the readOnly/openWorld/idempotent hints already provided.

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

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

The description is lengthy but every section carries relevant information: trigger phrases, usage, two pipeline paths, verdict meanings, and a critical warning. It is not front-loaded in the traditional sense but structured with an 'IMPORTANT' callout that earns its place. Slightly verbose but justified by the tool's complexity.

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

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

With no output schema, the description thoroughly covers return values (verdict list), citations, reasoning, and error semantics. It also explains the two routing paths, making the tool's behavior fully predictable. For a 2-param tool with complex runtime behavior, this is complete.

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

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

Schema coverage is 100%, with both parameters fully described in the input schema. The description adds examples for 'claim' and explains the default tolerance behavior, but it does not significantly extend parameter understanding beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as natural-language claim verification with specific trigger phrases and a clear verb-resource pairing (verify claim). It distinguishes from siblings like deep_research or ask_pipeworx by focusing on factual verification with verdict outcomes.

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,' providing clear context. It also differentiates between financial and non-financial claims, but does not name specific alternative tools for exclusion, keeping it at a clear-context level without explicit when-not usage.

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