Bamboohr

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses integration behavior: calling Anthropic with a BYO key and that the user pays Anthropic directly. It also specifies the default free model and the per-model plus combined return shape, which helps the agent anticipate side effects and external costs.

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

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

Three sentences, front-loaded with the core functionality, then model options, return format, and use cases. No fluff.

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

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

Without an output schema, the description compensates by listing the per-model return fields (score, confidence, signals, raw_response) and the combined view. Combined with the annotations and schema, the agent has enough to select and invoke the tool.

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

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

All four parameters have rich descriptions in the schema (100% coverage), and the description adds the specific default model name (Llama-3.3-70b) and the cost/dependency relationship for _apiKey. This elevates it slightly above baseline 3.

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

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

The description opens with a specific verb ('Probe'), identifies the resource ('one or more LLMs'), defines the output ('score visibility 0-100 per model'), and includes concrete examples in the schema. It clearly differentiates from sibling tools like ask_pipeworx and compare_entities by focusing on measuring AI awareness rather than generating responses or comparing entities.

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 states concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which tells an agent when to invoke it. However, it doesn't explicitly name alternative tools for those use cases or provide exclusions, so it earns a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it routes questions to 5,462 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This disclosure is consistent with annotations and enriches the agent's understanding.

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 average but every sentence serves a purpose: positioning, routing explanation, usage guidance, examples, and alternative escalation. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured to flow from general guidance to specific examples. Slightly verbose but not wasteful, earning a 4.

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

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

For a general-purpose question-answering tool with no output schema, the description thoroughly covers the tool's role, coverage, return format, performance characteristics, and relationship to alternatives. Annotations cover safety and idempotency. The schema covers parameters completely. No gaps that would impede correct selection or invocation.

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

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

Schema description coverage is 100%, with all six parameters being aliases for the same 'question' field, each fully documented in the schema. The description itself does not add parameter-level details beyond the schema, but the schema already handles the semantics. The examples provided in the schema reinforce usage. 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 answers factual questions about real-world entities using authoritative structured data with citations. It uses a specific verb ('ask') and names the resource (Pipeworx). It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making the purpose unambiguous.

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

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

The description gives explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives ('Step up only when needed...'). It provides concrete examples of query types and contrasts with ask_pipeworx_grounded and deep_research, offering clear decision criteria.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the beta/experimental nature, live candidate routing improvements, the current no-active-candidate status, and the comparison against the stable router for merge decisions. This adds meaningful behavioral context that annotations alone do not capture.

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 four-sentence description is front-loaded with the core definition and status, and every sentence contributes essential information about beta status, usage, and fallback behavior. There is 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?

No output schema is present, but the description explicitly states 'same response shape' as ask_pipeworx, leveraging that sibling tool's contract. It covers current experimental status, usage, and equivalence, though a standalone agent unfamiliar with ask_pipeworx might still lack detail about router capabilities.

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 all six parameters are fully documented (with aliases explained), so the baseline of 3 applies. The description adds only 'same arguments' but no additional parameter-level meaning; the schema already handles the semantics.

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

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

Description explicitly identifies the tool as 'Beta version of ask_pipeworx: identical universal router' with the same 5,462 tools, arguments, and response shape, clearly distinguishing it from the sibling ask_pipeworx and ask_pipeworx_grounded. The purpose — a live experimental routing variant — is stated unambiguously.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing explicit context for when to choose this tool. It also notes the current state (no active candidate, matches ask_pipeworx exactly) and that results are compared against the stable router, but it does not explicitly enumerate when not to use it or mention grounded alternatives.

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

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

The description discloses behavior beyond the annotations: it explains the refusal mechanism with specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), guarantees the answer uses only tool result content, and notes the extra LLM call cost. The annotations already declare readOnly and non-destructive, and the description aligns with them.

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

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

The description is front-loaded with the core purpose and includes dense, valuable information. While slightly long, every sentence adds necessary details (return format, refusal reasons, usage context, cost note), so it is well-structured for an AI agent.

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

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

For a tool with no output schema, the description thoroughly covers return values, refusal cases, and the trade-off with the sibling tool. It gives the agent all necessary context to invoke it correctly and interpret its result, and it clearly distinguishes when to use it versus ask_pipeworx.

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% as all parameters are documented as aliases for the question field. The description does not add additional parameter-level semantics beyond the schema, which is acceptable given the high coverage.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' which clearly states the tool's specific function. It further distinguishes this from sibling ask_pipeworx by explaining it 'EXTRACTS the answer using ONLY what the tool result contains' and explicitly says 'prefer ask_pipeworx for casual 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?

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'), which helps the model decide between 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds what data is returned but does not disclose other behavioral traits such as pagination, rate limits, or required permissions, which are not covered by annotations.

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

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

The description is a single, efficient sentence with no redundant or filler content. It conveys the essential purpose and output fields in a well-structured manner.

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 read-only tool with annotated safety, the description adequately covers the tool's function and data content. The presence of an output schema further reduces the burden of describing return values. Slightly higher than minimum because it clarifies the scope of the directory query.

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 are fully documented in the schema with clear descriptions ('BambooHR API key', 'BambooHR subdomain'), achieving 100% schema coverage. The description adds no parameter-specific detail, so baseline of 3 is appropriate.

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

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

The description clearly states the tool fetches the 'complete employee directory' and enumerates specific data types (names, titles, departments, contact info, manager assignments). This distinguishes it from sibling tools like get_employee (single employee) and list_employees (likely a simpler list) by emphasizing 'complete' and 'all staff.'

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

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

The description implies usage for retrieving comprehensive employee directory data but does not explicitly state when to use this tool over alternatives. No exclusions or comparisons to siblings are given, so guidance is implied rather than explicit.

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, so the safe read-only nature is covered. The description adds 'Returns requested data,' which is consistent with annotations, but does not provide additional context such as rate limits or error handling. 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 main purpose, and includes a concrete example. Every sentence earns its place with no filler or redundant content.

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

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

For a simple read-only lookup tool, the description is sufficient. The output schema and parameter schema provide complete detail, and annotations cover safety. It lacks explicit alternative guidance, but the tool's simplicity makes this acceptable.

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 all four parameters with examples and specifications. The description repeats some of this (e.g., fields like firstName, lastName) but adds no new semantic meaning beyond what the schema provides. Schema coverage is 100%, so baseline 3 applies.

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

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

The description uses a specific verb ('Get') with a clear resource ('detailed employee info') and an explicit identifier ('by ID'). It provides example field values and differentiates from sibling tools like list functions by emphasizing single-employee lookup.

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

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

The description implies usage for single-employee lookups when an ID is known, but it does not explicitly state when to use this tool versus alternatives like bamboohr_list_employees or bamboohr_get_directory. No exclusions or alternative names 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 this as read-only, idempotent, and non-destructive. The description adds the return fields (file names, upload dates, file types) but no additional behavioral context like pagination or permission requirements. This is acceptable given the annotations.

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

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

The entire description is one focused sentence: action, resource, and return summary. No wasted words or redundant details.

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

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

The tool is simple, annotations cover safety, schema covers all parameters, and an output schema exists. The description provides enough 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 parameters are fully described ('Employee ID', 'API key', 'subdomain'). The description's 'by ID' merely restates the id parameter, adding no new semantic value. 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 uses a specific verb ('Get'), identifies the resource ('files in an employee's profile'), and mentions the input ('by ID'). It clearly distinguishes from sibling tools like get_employee and list_employees by focusing on files.

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 context is clear: use this tool when you need an employee's files by ID. However, it doesn't explicitly mention when not to use it or point to alternatives, so it falls short of a full 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, covering the safety profile. The description adds no additional behavioral context such as pagination, rate limits, or authorization requirements. The mention of return fields is redundant given the existence of an output schema.

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, front-loaded with the primary action and followed by a concise list of return fields. There is no wasted verbiage, making it highly efficient.

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

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

For a simple list operation with two well-described parameters and an output schema, the description is adequate but minimal. It lacks any caveats about scope (e.g., active vs. terminated employees) or limitations, and does not clarify the relationship to sibling tools like 'bamboohr_get_directory'.

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 (_apiKey and _subdomain) described in the input schema. The description does not add any parameter-specific semantics, 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 has a specific verb ('List') and resource ('all employees'), making its primary action clear. It returns directory info with explicit fields, but it does not explicitly distinguish itself from the sibling tool 'bamboohr_get_directory', which may also list employee information.

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

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

No guidance is provided on when to use this tool versus alternatives like 'bamboohr_get_employee' or 'bamboohr_get_directory'. The description only states what it does, without context for selection.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the bar for disclosure is met. The description adds behavioral context by specifying what the response contains (approved/pending requests, employee names, absence types) and by providing a concrete example of the date range syntax. This goes beyond the annotations without contradicting them.

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

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

The description is only two sentences long, front-loaded with the core action and resource, and includes a practical example. Every sentence earns its place: the first defines the operation, and the second specifies the output content. There is no wasted text or repetition of structured data.

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 4-parameter query tool with a well-annotated safety profile, a complete output schema, and a description that covers both usage and return content, the description is fully adequate. It provides the necessary information for an agent to select and invoke the tool correctly without ambiguity. No additional context is needed.

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 all four parameters, each with clear descriptions (e.g., 'End date (YYYY-MM-DD)'). The description's mention of a date range adds no new semantic meaning beyond what the schema already offers. Baseline 3 is appropriate because the schema does the heavy lifting with limited additional value from the description.

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

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

The description clearly states a specific action ('Search time-off requests') and resource ('time-off requests by date range'), making its purpose unmistakable. It distinguishes itself from sibling tools like bamboohr_list_employees and bamboohr_get_employee by focusing on time-off data, and it adds specifics (approved/pending, employee names, absence types) that reinforce its unique role.

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

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

The description provides clear context for when to use this tool: when searching time-off requests within a date range. It does not explicitly exclude alternatives or name sibling tools, but the domain is so well-defined that an agent can easily infer when this tool is appropriate versus the other BambooHR tools. The example date range further clarifies the intended use case.

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

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

The description goes far beyond the readOnlyHint/openWorldHint annotations by detailing fan-out behavior, response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives, suggestions), parent_event extraction, news fallback mechanics, safety statuses, and resolution-rule risk. This is exemplary behavioral disclosure.

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 exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section provides unique operational detail. While it could be trimmed slightly, the density is justified given the tool's complexity; the front-loaded purpose sentence ensures rapid orientation.

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?

There is no output schema, so the description carries full responsibility for documenting return values. It comprehensively covers all response fields, edge cases (illiquid spread, low-confidence match, closed markets), and the resolution-rule risk that affects sizing. The description leaves no critical behavior 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?

Schema description coverage is 100%: all three parameters (market, depth, include_raw) have descriptive schema entries. The tool description does not add significant semantic value beyond the schema, though it reinforces accepted market input formats with examples. 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies scope by enumerating classifiers and fan-out examples, which clearly distinguishes it from sibling tools like polymarket_edges or validate_claim.

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 cues are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool blocks (low-confidence match, closed/dead markets) and how to interpret ambiguous results, giving agents clear decision rules.

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 (read-only, open-world, idempotent), the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting behavior by primary metric, and return format (paired data + pipeworx:// citation URIs). This is rich behavioral context that exceeds 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?

The description is dense but efficiently packs trigger examples, usage guidance, data source details, and return format into a single paragraph. It is front-loaded with query patterns and every sentence adds value, though it could be slightly more structured for scannability.

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

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

With only 2 parameters and no output schema, the description fully compensates: it states what data is pulled per type, how results are sorted, what is returned (paired data + citation URIs), and the scale of efficiency gain (replaces 8-15 sequential lookups). An agent can confidently select and invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics by detailing what metrics each type pulls (revenue, net income, cash, debt for companies; adverse-event counts, FDA approvals, trials for drugs) and examples of values (tickers vs drug names). This goes beyond the schema's simple descriptions.

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

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

The description uses a specific verb ('compare') with a clear resource ('entities' — companies or drugs) and explicitly lists trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sibling tools like entity_profile by focusing on side-by-side comparison in one parallel call.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive on when to use it. It also differentiates between company and drug types. It does not name specific alternative tools but implies entity_profile for single-entity lookups, which is sufficient.

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

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

Even though annotations already mark readOnlyHint=true, the description adds substantial behavioral context beyond that: account requirements (free GitHub sign-in, paid plan for the 'thorough' depth), expected latency (15-60s, up to ~90s), depth-specific behaviors (gap recovery, contradiction scanning), semantic excerpting of large records, and the guarantee that every citation_uri is resolvable. This goes far beyond the annotations and fully discloses operational behavior.

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

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

The description is long, but it is densely packed with essential information and well-structured. It front-loads the critical account requirement, then proceeds logically through core function, output contents, use cases, depth semantics, and technical details. Every sentence earns its place, though some could be trimmed without loss. 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?

The description is exceptionally complete given the tool's complexity and lack of an output schema. It specifies the exact contents of the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), describes the 'hop' field and citation_uri, mentions latency, and addresses edge cases like topics not in the structured catalog. An agent can fully anticipate what will happen.

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

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

The schema already describes the parameters, but the description enriches their meaning. It clarifies that 'question' can be broad/multi-part ('Broad/multi-part is fine — decomposition is the point') and explains the practical implications of each depth level, including that 'thorough' is paid and how each depth changes the research process (single hop, gap recovery, iterative chases). This adds value beyond the bare schema definitions.

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

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

The description precisely states the tool's function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources ... in ONE call' and clearly distinguishes it from siblings by explicitly contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx') and noting it is 'NOT open-web search.' This is a specific verb+resource+scope that leaves no ambiguity.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also gives an account-based alternative ('If you are not signed in, use ask_pipeworx instead'), making alternatives crystal clear.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable context beyond these: it returns top-N relevant tool names, descriptions, and full input schemas with curated examples, ready for direct invocation with no second lookup. It also clarifies that it is a discovery mechanism, not a data-access tool.

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

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

The description is front-loaded with the core purpose and then elaborates on usage, output, and prioritization. The list of domains is useful but slightly verbose; every sentence contributes, though some phrasing is repetitive (e.g., 'browse, search, look up, or discover'). Overall, it is concise and well-structured.

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

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

Given that this is a discovery tool with no output schema, the description covers all key aspects: what it does, when to use it, what it returns (top-N tools with schemas and examples), and how to prioritize it. The information is sufficient for an agent to invoke it correctly without needing further clarification.

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

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

Schema description coverage is 100%, with explicit descriptions for the 'query' parameter and aliases, plus the 'limit' parameter. The tool description reinforces that queries are natural language descriptions, but adds little beyond what the schema already states, so 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 finds tools by describing a data or task, listing many domains. It distinguishes itself from sibling tools by positioning as a meta-tool for discovery, with the explicit directive to 'Call this FIRST' when many tools are available.

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: browse, search, look up, or discover tools, with a list of example domains. It also tells the agent to use it FIRST when exploring options, though it does not explicitly name alternative tools or state when not to use it.

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 specific behavior: it 'fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF,' returns several detailed fields, and notes the USPTO PatentsView API sunset with soft-fail behavior. It also mentions the GDELT→GNews fallback for news. This is rich behavioral context that helps the agent set expectations and handle partial failures.

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 each section serves a purpose: examples for user intent, a clear capability statement, then a detailed fan-out and return-field breakdown. It is front-loaded with natural-language triggers. Minor redundancy exists between the opening 'full cross-source profile' and the later 'Fans out,' and the return-field list is dense, but overall it is well-structured and no sentence is wasted.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly covers expected returns (cik, company_name, recent_filings with URIs, fundamentals with sorting, patents, news, LEI). It also covers edge cases (names not supported, patent API sunset soft-fail). This is sufficient for an agent to know exactly what to expect and how to handle limitations.

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

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

The schema already provides full descriptions for both parameters, including the enum for type and the value description. The description adds concrete examples ('AAPL' or '0000320193') and reinforces the naming restriction, which is helpful but not strictly necessary given 100% schema coverage. This elevates it slightly above the baseline of 3.

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

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

The description identifies the tool's core function as building a full cross-source profile of a US public company given a ticker or CIK. It is specific about the resource (US public company) and the verb (profile), and explicitly contrasts with 'chaining single-pack SEC/XBRL/news lookups,' which differentiates it from simpler sibling tools. Trigger examples ('Tell me about X', 'research Acme') further clarify intended use.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a concrete exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives clear decision rules for the agent against alternative tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context that it deletes 'previously stored' memory and mentions clearing sensitive data. It does not contradict annotations, but could add nuance about missing keys or permanence, though destructiveHint covers that. Good but not exhaustive.

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

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

Two sentences with the core action front-loaded in the first sentence. The second sentence adds usage guidance. Zero waste, highly scannable.

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 1-parameter tool with no output schema, the description covers purpose, usage timing, and relationship to sibling tools. It is fully self-sufficient and leaves no critical gaps.

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

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

Schema coverage is 100%; the parameter 'key' is already described as 'Memory key to delete'. The description repeats this without adding extra format, examples, or constraints beyond what the schema provides. Baseline 3 applies.

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

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

The description opens with 'Delete a previously stored memory by key', which is a specific verb (Delete) and resource (memory by key). It clearly distinguishes from siblings like remember (store) and recall (retrieve), making the tool's purpose unmistakable.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also directs pairing with remember and recall, offering guidance on alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds process detail, noting it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which goes beyond the annotations by describing the fetch and extraction behavior. It also states the output is a 'single text blob,' providing return format clarity.

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

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

The description is three sentences long, front-loading the core purpose, then process, then use cases. Every sentence provides unique value with no redundancy or fluff, making it efficient and well-structured.

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

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

Given the tool's simplicity (2 params, rich annotations, no output schema), the description is complete. It explains the output format ('Output is a single text blob ready to drop at site-root/llms.txt'), the process, and common use cases. Nothing critical is missing for an agent to invoke and understand the result.

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 both 'url' and 'max_links' are already well-documented with types, defaults, and constraints. The description adds no additional parameter details beyond what the schema 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 it 'Generate[s] a production-ready llms.txt file for any URL', combining a specific verb with a specific resource and output format. It also distinguishes itself from related sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on generating the standard llms.txt file rather than just checking visibility.

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 with 'Useful for:' scenarios such as getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor. It does not explicitly name alternative tools or list when not to use, but the context is sufficiently clear for an agent to decide when 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context such as scope ('caller's subscriptions') and return fields ('id, type, params, created_at, last_fired_at, fire_count'), which goes beyond the annotation-only view. However, it doesn't explicitly mention the include_inactive filter 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 two sentences, with the first stating the function and return fields, and the second giving usage guidance. Every sentence earns its place, with no superfluous words.

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

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

For a simple read-only list tool with rich annotations and full schema coverage, the description is complete. It states purpose, return values, and when to use it, requiring no additional information for an agent to invoke it correctly.

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

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

The schema already fully documents the only parameter (include_inactive) with its description and default. Schema coverage is 100%, so the description doesn't need to add parameter details; it adds no parameter-specific meaning but 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 clearly states the action: 'List the caller's active subscriptions.' It also specifies the returned fields, making it distinct from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and for what purpose, effectively differentiating it from subscription-modifying tools.

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

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

Annotations only indicate non-read-only and non-destructive, but the description adds critical behavioral context: rate-limited to 5 per identifier per day, free (doesn't count against quota), and that the team reads digests daily. It also warns not to include end-user prompts, which is a privacy-related behavioral guideline not captured by annotations.

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

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

The description is compact yet dense, with every sentence contributing purpose, usage constraints, or exclusions. It opens with a clear action statement, followed by conditions, boundaries, and operational details. No fluff; each sentence earns its place.

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

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

Given the tool has no output schema and is a feedback submission mechanism, the description fully covers the 'when', 'what', 'how', and 'why not' with rate limits, format guidance, and team responsiveness. It is complete for an agent to decide and use the tool correctly.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and to avoid pasting end-user prompts, which clarifies content expectations beyond the schema. This extra guidance elevates it above the baseline.

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

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

The description clearly states the verb 'Tell' and resource 'Pipeworx team', specifying that it reports broken, missing, or desired functionality. It distinguishes itself from siblings like ask_pipeworx by focusing on feedback to the team rather than querying information.

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

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

The description explicitly lists when to use (bug, feature/data_gap, praise) and when not to (feedback about other MCP servers). It also provides an alternative action ('file it with that server instead') and clarifies how to identify Pipeworx-owned tools, making usage conditions unambiguous.

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

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

The description adds behavioral detail beyond the annotations: it explains the data source ('derived from CF analytics-engine'), guarantees no PII, and discloses caching behavior ('Cached 5min-1h depending on window'). This contextualizes what the read-only operation returns and how fresh the data is, going well beyond the annotations themselves.

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 compact and efficiently structured: a direct statement of outputs, a bulleted list of use cases, and a final sentence on technical details. Every sentence earns its place, with no redundancy or filler.

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 optional parameter, no output schema), the description is complete. It covers the return shape explicitly ('just (pack, tool, count)'), caching behavior, and the window parameter's semantics. The agent has all necessary context to invoke the tool correctly.

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

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

The schema already describes the window parameter with an enum and default, but the description enriches it by explaining the semantic trade-off: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds actionable meaning beyond the raw schema definition.

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

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

The description opens with a clear statement of what the tool does—'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'—and adds concrete use cases. This specificity distinguishes it from sibling tools like discover_tools, as it focuses on aggregate call volume rather than individual tool discovery.

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 enumerates three useful scenarios (discovering hot data sources, confirming canonical tool choice, assessing alignment with other agents' needs), providing clear context on when to use this tool. It does not name alternatives or state when not to use it, but the guidance is strong enough for a 4.

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

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

The description discloses rich behavioral details beyond the readOnly/openWorld/idempotent annotations: the 3pp partition deviation threshold, 0.30 Jaccard similarity anchor, placeholder slug filtering with >20% fraction returning null, and the fill-check behavior against live CLOB depth. 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 densely packed and well-organized with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose statement. Each sentence serves a distinct purpose, from mode selection to response format to trade safety, so 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?

Given the tool's complexity and lack of an output schema, the description covers all essential aspects: modes, thresholds, edge cases (placeholder filters, low similarity), response structure (opportunities[], partition_check, fill_check fields), and cross-references to polymarket_fill_risk for custom sizing. 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?

Although schema_description_coverage is 100%, the description adds substantial meaning beyond the schema: it explains the no-args default, provides example event slugs and seed topics, clarifies the difference between single-event and cross-event modes, and details thresholds and response fields associated with each parameter. This is far more than the schema's brief descriptions.

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

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

The description opens with a clear, specific verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes three modes (no-arg trending_scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk, making the tool's function unmistakable.

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

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

Usage guidance is explicit and actionable: 'Call with NO args for a trending_scan... pass event for... or topic for...' with concrete examples for each mode. It also tells when to use an alternative ('For custom sizing use polymarket_fill_risk') and warns against trading when realizable_edge_pp ≤ 0, providing clear when-not 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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds enormous behavioral detail: the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), specific model formulas (lognormal barrier from 90d FRED log-returns, GDELT volume ratio), edge metrics (edge_pp_net, kelly_fraction_half), the 24h-move warning, placeholder-slug filters, per-sport α values, and the caching behavior. It also discloses why Fed bets are excluded. This is exactly the kind of context that helps an agent trust and interpret the tool.

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 and information-dense, but every sentence contributes unique details about the tool's internal logic or usage. It uses effective structuring with parentheses and semicolons to pack in model parameters and conditions. It could be slightly more concise (e.g., breaking into paragraphs or bullets), but for the complexity of the tool, the density is justified.

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 must explain return values, and it does so thoroughly: the top-level by_segment, fed_candidates/fed_note, and _diagnostics structure, plus the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers the full pipeline from opportunity generation to filtering, including edge cases like placeholder-slug filters and the rare-by-design longshot basket. This is complete enough for an agent to invoke the tool and understand the response.

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 with detailed descriptions for every parameter, so the baseline is 3. The description adds extra meaning by connecting knobs to their purpose: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also hints at how to set them (e.g., 'Set to 5000 to drop thin-book opportunities'). This goes beyond the schema's field-level descriptions by explaining the strategy behind the knobs.

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 begins with a specific action and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also differentiates from sibling tools by stating it is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This makes the tool's purpose unmistakable and distinct.

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 on when to use the tool: for discovering opportunities across top Polymarket markets without paging through hundreds. It also explains the tradeable-edge knobs and the diagnostics section, which helps the agent understand how to interpret results. However, it does not explicitly mention when to prefer sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it lacks explicit exclusions.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavior beyond the structured fields: it explains that snapshots are written on cache-miss, gaps mean nobody scanned, history is bounded by the 60-day TTL, and decay is computed from daily closes (net of default slippage) rather than intraday. It also details the response shape, which is absent from an output schema.

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: clear purpose, explicit arg explanations, a structured RESPONSE section, and LIMITS. Every sentence carries useful information—there's no filler. The use of labels like 'Args:', 'RESPONSE:', and 'LIMITS:' makes it scannable despite 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?

With no output schema and a moderately complex tool, the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, and all relevant edge cases (TTL, gaps, signed edge_pp_net). It leaves no critical behavioral aspect 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?

The schema already covers both parameters with good descriptions (100% coverage), so the baseline is 3. The description adds value by explaining 'window' as a 'snapshot family' and clarifying that 'days' is the lookback period with default/max values. It also ties the parameters to the response behavior (snapshot_dates), which enhances understanding beyond the schema alone.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly differentiates from the sibling tool polymarket_edges by focusing on persistence/decay over time rather than current edges. The rhetorical question 'how long has this edge existed and is it shrinking?' defines its exact scope.

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

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

The description provides explicit use context: it answers whether an edge is fresh or old, and explains why that matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also discloses the TTL limitation and the reason for snapshot gaps. However, it doesn't name alternative tools or state 'when not to use', though the uniqueness of persistence tracking is implied.

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

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

Beyond the readOnly/idempotent annotations, the description discloses operational behavior: it walks the order-book ladder, distinguishes top-of-book vs VWAP fills, identifies thin legs, and reports forced directional risk. It also cautions about partial fills stranding the user unhedged.

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 dense, front-loaded paragraph. While it's long, every sentence carries critical context for a complex tool; the key statement appears first and the rest follows logically. It earns its length.

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

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

With no output schema, the description itemizes return values for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs[], etc.) and explains the risk context. It also covers parameter behavior and limitations, making it a fully self-contained guide 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?

The input schema already provides detailed descriptions for all four parameters and 100% coverage, so the baseline is 3. The description adds the requirement that one of market/event must be passed and explains default side selection in basket mode, but this is marginal beyond schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly positioning itself as the risk-check to run before those trades.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the failure mode (partial basket fills converting arb into unhedged position) and covers both single-market and basket modes.

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 and idempotent annotations, the description discloses rich behavioral details: compatibility_warning logic, temporal_alignment meaning, skipped_cross_type/subtype counters, and the interpretation of matched_pairs:0. It even explains that pre-mapped ≠ tradeable, revealing limitations. This significantly 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 every sentence carries substantive information about modes, response fields, safety flags, and caveats. It is front-loaded with the core purpose, but the single-paragraph structure makes it dense and harder to scan. The content justifies the length, though a clearer structure would improve readability.

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 response fields (leg prices, spread, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counts), and edge cases. It covers the tool's complexity, including why a zero pair count can mean two different things, making it complete for an agent to 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?

Although the schema covers 100% of parameters, the description adds essential semantics: it explains the relationship between 'topic' and the explicit override parameters ('Overrides the topic-mapped side'), and illustrates the two modes with a clear mapping to the parameters and their roles. This goes beyond the basic 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' using a specific verb+resource structure. It distinguishes from sibling tools (e.g., polymarket_arbitrage) by focusing on cross-venue comparison, and details two operational modes, 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 clear usage context by explaining two modes (topic shortcuts vs. explicit identifiers) and when each is appropriate. It warns that pre-mapped topics often return compatibility_warning and thus aren't necessarily tradeable, but it does not explicitly name alternative tools or state 'when not to use this tool' in favor of another sibling. This is clear context without explicit exclusions.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read operation. The description adds valuable context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieve/list behavior. It doesn't need to repeat safety traits already declared.

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, each earning its place: the core action, the use case, the scoping detail, and the pairing with sibling tools. It is front-loaded with the primary behavior and contains 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 tool with one optional parameter, no nested objects, and strong annotations, this description is complete. It covers retrieval, listing, scope, and relationships to remember/forget. The lack of an output schema is not a gap given the simplicity of the expected response.

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

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

Schema coverage is 100% with the 'key' parameter fully described. The description adds meaning beyond the schema by explaining that omitting the key triggers a list-all-keys action, and gives concrete examples of what keys might contain. This supplements the schema without redundancy.

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

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

The description starts with a specific verb ('Retrieve') and names the resource ('a value previously saved via remember'), then immediately distinguishes the two modes: retrieving by key or listing all keys. This clearly differentiates it from sibling tools like remember and forget while stating its exact function.

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

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

Explicitly states when to use the tool: to look up context the agent stored earlier (e.g., user's target ticker, address, research notes), and emphasizes avoiding re-derivation. It also names complementary tools: 'Pair with remember to save, forget to delete.' This gives clear contextual 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 annotations declare readOnlyHint=true, but the description explicitly states that setting mark_read:true flags events as read, a state-changing side effect. This is a direct contradiction between the description and the readOnlyHint annotation, making the tool's safety profile confusing for the agent.

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

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

Three sentences, front-loaded with purpose, then return format, filters, mark_read semantics, and an alternative access method. Every sentence contributes information with no fluff or redundancy.

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

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

Given 5 parameters and no output schema, the description covers the main return contents, filtering options, and the mark_read side effect. It omits details on limit and unread_only, but the schema already handles those. The tool's complexity is moderate and the description is largely sufficient, though the read-only contradiction undermines overall coherence.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds a concrete example for type ('sec_8k'), clarifies ISO format for since, and explains the behavioral effect of mark_read. This goes beyond the schema and compensates for any ambiguity.

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 and resource: 'Pull fired events from your subscription feed' and clarifies it returns alerts written by the evaluator. It is specific but does not explicitly differentiate from sibling tools like recent_changes or list_subscriptions, so it misses the top score.

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 practical context ('Polls work fine', external endpoint for scripts) and explains mark_read behavior, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage is implied rather than fully spelled out.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing the fan-out to SEC EDGAR, GDELT→GNews fallback behavior, and the USPTO soft-fail due to API sunset. It also specifies output structure (changes[] grouped by source, total_changes, pipeworx:// citation URIs), which is valuable since no output schema 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 front-loaded with example user queries and then systematically covers behavior, parameters, output, and alternatives. Every sentence contributes distinct information, and the structure is dense without being bloated. It is longer than minimal but appropriately sized for a tool with multi-source fan-out and fallback logic.

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 fairly complex tool with no output schema, the description covers the essential behavioral contract: input formats, source behavior, fallback mechanisms, output grouping, and a pointer to the alternative entity_profile tool. It is sufficiently complete for an agent to select and invoke correctly without additional 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?

Input schema covers 100% of parameters, so the baseline is 3. The description adds meaningful guidance beyond the schema, such as concrete examples of `since` formats ('7d', '30d', '3m', '1y'), the recommendation to use '30d' or '1m' for typical monitoring, and clarification that `value` can be a ticker or CIK. This extra context justifies a score above baseline.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with concrete natural-language triggers like 'What's new with X' and 'latest on Y'. It distinguishes itself from entity_profile by contrasting windowed changes with static profiles, making sibling differentiation strong.

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

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

The description explicitly states when to use this tool ('change feed for a company in the last N days/weeks/months') and gives explicit alternative guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' It also clarifies the intended user queries, making selection straightforward.

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 (idempotent, not destructive), the description adds valuable behavioral details: persistence (authenticated users persistent, anonymous 24h), scoping ('scoped by your identifier'), and its role in a memory lifecycle. This enriches the agent's understanding without contradicting annotations.

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

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

The description is three concise sentences that are front-loaded with the main purpose, followed by usage guidance and persistence semantics. No wasted words; every sentence provides distinct value.

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

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

For a simple tool with 2 required parameters and no output schema, the description is complete. It covers what, when, and how to use it, plus persistence and pairing with related tools. No critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description only adds that it's a key-value pair, which is already clear from the schema. It doesn't add new syntax or format details for parameters, so it doesn't exceed the baseline.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It specifies the resource (key-value store) and distinguishes it from siblings like recall and forget by explicitly mentioning those as complementary tools.

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

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

The description gives explicit usage context ('Use when you discover something worth carrying forward') with concrete examples. It also points to alternatives (recall, forget). However, it doesn't explicitly state when not to use the tool, 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 mark the tool as read-only, idempotent, and non-destructive, so the description adds substantial behavioral context: it details the specific return fields (ticker, CIK, RxCUI), the citation URIs, auto-disambiguation for company inputs, and the internal cascading through multiple lookups. This enriches the agent's understanding 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 moderately detailed but every sentence carries purpose: the query examples make the purpose immediately recognizable, the 'Use FIRST' line is a crisp directive, and the supported-type breakdown is logically structured. No redundancy or filler is present, and it remains front-loaded with the core purpose.

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

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

Given the tool's complexity (two entity types with distinct output formats) and the absence of an output schema, the description thoroughly covers returns for each type, input flexibility, disambiguation behavior, and citation URIs. It is self-contained and sufficiently complete for an agent to select and invoke the tool correctly without 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?

Although the schema already describes the two parameters and has 100% coverage, the description adds significant value by providing concrete examples (AAPL, 0000320193, ozempic) and clarifying the accepted input forms for each entity type. This helps the agent map user intents to the correct parameter values, especially the flexible 'value' parameter.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific verbs like 'resolve' and a defined resource scope (company/drug identifiers). It includes concrete example queries and explicitly names the underlying data sources (SEC EDGAR, RxNorm), which distinguishes it from sibling tools focused on profiles or comparisons.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, indicating efficiency. However, it does not explicitly state when not to use it or mention an alternative tool for cases where an ID is already available, so it falls short of a full 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, idempotentHint, and openWorldHint. The description adds meaningful behavioral context: that it probes each entity via ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. No contradiction with annotations.

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

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

The description is concise: it states the purpose first, then the method, a usage example, and the return format. Every sentence contributes value, with no redundancy or filler.

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 multi-entity comparison tool with no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density) and the workflow. It could mention alternatives like compare_entities, but the core information is present.

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%, including detailed notes on entities as the subject/competitors and the models/_apiKey interplay. The tool description adds no additional parameter semantics beyond the schema, 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 opens with 'Compare AI visibility across multiple entities side-by-side,' which clearly states the verb ('Compare') and resource ('AI visibility'). It distinguishes itself from sibling ai_visibility_check by emphasizing the multi-entity, side-by-side comparison and ranking aspect.

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 context: 'Useful for competitive AI-marketing audits' with a concrete example query. It does not list exclusions or alternatives, but the context is strong enough to infer when to use it versus the single-entity ai_visibility_check.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial behavioral context: it performs composite fan-out across two services, handles partial failures gracefully, warns about 5-30s latency for first bundlephobia measurement, and discloses that failures appear in sources_failed. This goes well beyond the annotation baseline.

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

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

The description is concise for the richness of content, front-loading the core purpose in the first clause. It efficiently covers composite behavior, usage triggers, return summary fields, ecosystem limitations, and edge-case latency. Every sentence contributes unique value.

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

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

The tool is complex (multi-source composite with potential timeouts), but the description covers purpose, when to use, return values (summary block fields, per-advisory detail, links), ecosystem scope, and graceful degradation. With no output schema, this description sufficiently fills the gap.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (package and version). The description does not add parameter-level meaning beyond what the schema provides; the mention of 'latest published version' in schema is clear. 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 describes a composite npm package analysis tool ('should I add this npm package to my project' check in ONE call) that fans out across deps.dev and bundlephobia. It specifies the exact resource (npm packages) and the specific aggregate function, distinguishing it from sibling research tools.

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

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

The description explicitly states when to use this tool ('Use whenever an agent asks...') and gives concrete examples. It also excludes non-NPM ecosystems and points to deps.dev:version directly for PyPI/Maven/Cargo/Go, which serves as an 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?

Beyond the readOnlyHint and idempotentHint, the description discloses implementation details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. It also specifies output traits like character offsets and similarity scores, adding meaningful 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 slightly long but front-loaded with the core purpose. Each sentence adds value: usage context, pairing with another tool, and technical details. No fluff, though it could be trimmed slightly without losing key information.

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

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

Given no output schema, the description explains the return format ('top-N passages with character offsets and similarity scores'), which is essential. It also covers the input domain, truncation behavior, and relationship to sibling tools. Minor gaps include error handling or exact output formatting, but overall it is complete for a moderate-complexity 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 thorough descriptions for all three parameters (100% coverage), so the description adds minimal new meaning. It does reinforce the 'natural-language query' concept and mentions 'top-N passages' which relates to the limit parameter, but this is largely redundant with the schema.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record', specifying the verb (search) and resource (fetched record). It distinguishes itself from siblings by focusing on already-pulled text rather than external sources, and even references ask_pipeworx_grounded as a complementary tool.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt', providing a clear when-to-use scenario. It also mentions pairing with ask_pipeworx_grounded for grounding over relevant passages, offering an alternative workflow. However, it could more explicitly state when not to use this tool versus 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 goes far beyond the annotations by disclosing authentication requirements, delivery channel specifics, and behavioral nuances: 'phone must be verified at /account first; 10/day cap', 'webhook... Auto-disabled after 10 consecutive failing runs', and 'Signing secret returned once at subscribe time.' It also clarifies that the feed is always on and how to pull alerts via recent_alerts or a public endpoint. 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 dense but well-structured: a crisp opening sentence, followed by auth requirements, type-specific examples, and then delivery channel details. It front-loads the core purpose and return value. While long, the complexity of three parameters with nested objects and multiple subscription types justifies the length; no sentence is wasted.

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

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

With no output schema, the description adequately explains that it returns 'the new subscription id' and mentions the one-time webhook secret. It covers authentication, all supported subscription types, delivery options, and failure behaviors. The description is fully self-contained for an agent to select and invoke 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?

The schema already covers all parameters with rich descriptions (100% coverage). The description adds contextual meaning beyond the schema, such as interpreting items:["5.02"] as 'officer change' and giving concrete examples like params:{topic:"fed"} and series_id:"UNRATE". It also elaborates on delivery channel semantics, including webhook signing, which the schema only partially covers.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb ('Create'), a clear resource ('subscription'), and notes the primary return value. It clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains when to use this tool by detailing supported subscription types (sec_8k, polymarket_edge, fred_series) and delivery channels, implicitly contrasting with siblings like recent_alerts for reading events and unsubscribe for removing them. It also states an explicit prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It doesn't explicitly mention a when-not-to-use, but the context is sufficient.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds behavioral context by stating it draws from the live catalog and returns structured examples with tool/argument shapes, plus the option to focus via topic. 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?

Though longer, the description is front-loaded with example user queries, then efficiently covers function, output content, parameter behavior, and when-to-use in densely informative sentences. Every sentence earns its place for an onboarding 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 simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, output content, and contextual guidance. It provides all necessary information for an agent to invoke it correctly and understand what to expect.

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 semantic value beyond the schema by explaining the `topic` parameter is optional, providing examples ('finance', 'pharma', 'betting'), and clarifying that omitting it returns a cross-category spread.

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: an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It uses specific verbs ('Returns', 'draw from the live catalog') and distinguishes itself from siblings by positioning it as the first step when unsure about Pipeworx capabilities.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and clarifies when to pass a topic versus call with no arguments. It also mentions learning how to call meta-tools, providing clear context for use even though it doesn't name alternative tools.

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

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

The description adds important behavioral context beyond the annotations: it states that ownership is enforced and that the row is deactivated rather than deleted, which clarifies the actual side effect. Annotations already declare destructiveHint:false, but the description explains why (soft delete).

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 short sentences that are information-dense with no unnecessary wording. It front-loads the action and provides essential caveats in a compact form.

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 annotations, the description covers the key aspects: what it does, ownership constraint, and side effect. It could mention return values or error conditions, but the absence is minor given the tool's complexity.

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

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

Schema coverage is 100% and the only parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantic meaning beyond the schema, hence baseline score.

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

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

The description clearly states 'Cancel a subscription by id', a specific verb+resource pair. It distinguishes the tool from siblings like subscribe and list_subscriptions by its action and effect.

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 (ownership enforcement, deactivation instead of deletion) and implicitly indicates when to use it (to cancel a subscription). It doesn't explicitly name alternatives or exclusion criteria, but the context is sufficient for most use cases.

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, openWorldHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: two execution paths (SEC EDGAR/XBRL fast path vs. grounded pipeline), live-source routing, verdict types, and citation/reasoning delivery. It also notes the tool replaces 4–6 sequential calls, giving efficiency insight.

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

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

The description is a single dense paragraph, but each sentence earns its place: usage trigger, routing logic, return contract, and efficiency claim. It's longer than average, but the complexity of the tool justifies the length; there is no redundant 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?

For a tool with no output schema, the description clearly enumerates return values (verdict types, grounded/structured actual value, pipeworx:// citation, reasoning). It explains both routing paths and usage boundaries. Combined with full schema coverage for parameters, the tool is completely 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 description coverage is 100%: both parameters (claim and tolerance_pct) have detailed descriptions, including examples and default behavior. The tool description adds minimal parameter value beyond the schema—only the natural-language claim phrasing examples. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly specifies a verb (validate) and resource (natural-language claim) against authoritative sources, with explicit example phrasings like 'fact check' and 'true or false'. It distinguishes from sibling research tools by focusing on true/false verification rather than open-ended queries or entity comparison.

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 states a clear usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates routing for company-financial claims vs. any other factual claim. It doesn't explicitly name alternative tools for when not to use, but the context is sufficiently clear.

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