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, openWorldHint, idempotentHint, and destructiveHint:false. The description adds useful behavioral context by saying the tool routes to 5,798 tools, fills arguments, and returns a structured answer with stable citation URIs. This meaningfully supplements the structured data and does not contradict any annotation.

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 key instruction is front-loaded, but the description is overly long for a single-parameter tool and ends in a confused, repetitive sentence about news feeds and '*'-packs. The large category list and examples add value, but the garbled tail and redundancy make the description noticeably undisciplined.

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

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

The description covers the main selection context, sources, output style, and example invocations, which is substantial for a one-parameter tool. However, it does not address the ask_pipeworx_beta and ask_pipeworx_grounded siblings, leaving the agent without guidance on when the base variant is preferred. The no-output-schema case means the citation-URI mention must do more work than it fully does.

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

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

Schema coverage is 100% and the schema already documents the required 'question' parameter plus all aliases. The description repeats the purpose of a natural-language question and provides examples, but it adds no parameter-specific meaning beyond what the schema gives. 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 what the tool does: it routes a natural-language question to one of many tools and returns a structured answer with stable pipeworx:// citation URIs. It names a broad coverage scope and explicitly positions itself over web search. However, it does not differentiate this tool from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description gives strong positive guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with trigger phrases and concrete example questions. It clearly says to start here for most factual questions. It does not discuss when to choose a sibling variant or state explicit exclusions, so it falls just short of full alternative routing.

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. The description adds meaningful context beyond that: beta status, live candidate routing experiments, current lack of an active candidate, comparison against the stable router, and clarification that it is a full working router rather than a disabled fallback.

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

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

The description is front-loaded with the key purpose but is noticeably redundant: 'identical universal router' is followed by a parenthetical repeating the same details, and 'currently matches ask_pipeworx exactly' is stated twice in different forms. It could be tightened without losing meaning.

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

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

For a read-only universal router, the description covers the current experimental state, usage instructions, relationship to the stable router, and return shape by referencing ask_pipeworx. The absence of an output schema is mitigated by 'same response shape', and the parameter schema is fully self-contained.

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 documented as aliases of 'question'. The description adds little beyond 'same arguments as ask_pipeworx', which is a useful cross-reference but not necessary since the schema already fully explains the parameter semantics.

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

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

The description clearly states this is the beta version of ask_pipeworx and identifies it as a universal router with the same tools, arguments, and response shape. It differentiates it from the stable ask_pipeworx by positioning it as the experimental routing edge.

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 instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains the current state (no candidate active) so the agent knows it currently behaves identically. This gives clear selection criteria without leaving the agent to infer.

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, non-destructive), the description adds rich behavioral context: it routes through tools, extracts only from fetched results, returns an evidence quote, and refuses with explicit reasons when data is insufficient. It also discloses the extra LLM call cost. 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 detailed but efficiently organized: core behavior first, then return format and refusal reasons, then usage guidance and cost tradeoff. Every sentence adds distinct value, and the structure leads with the most important 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?

Because there is no output schema, the description fully specifies the return shape, including success fields and all refusal_reason enum values. It also covers routing behavior, data-sourcing scope, cost implications, and when to choose the alternative. An agent has everything needed to call 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 description does not discuss the question parameter, but the input schema covers all six aliases with descriptions, giving 100% schema coverage. The schema's question parameter is clearly described as accepting natural language with alias names, so the baseline of 3 applies; the description adds no additional parameter nuance.

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 concrete purpose: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by highlighting grounded extraction from tool results and explicit refusal behavior, so an agent knows exactly what this variant adds.

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

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

It provides explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts, with concrete domains listed. It also names the alternative (ask_pipeworx), explains the cost tradeoff, and states the preference for casual lookups, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=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?

Annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive) already cover the safety profile, and the description adds substantial behavior beyond them: parallel routing across 5,798 tools, the never-invented gaps[] guarantee, contradictions[] scans, semantic excerpting rather than head-truncation, always-fetchable citation_uri mechanics, auth/paid-tier requirements, and timing expectations (15-60s, thorough up to ~90s). No contradiction with annotations — openWorldHint is consistent with research over live structured data.

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

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

Dense but front-loaded with the most critical constraint (ACCOUNT REQUIRED) and routing decision. Every sentence carries information for a complex tool with 3 depth modes, auth tiers, and a rich output packet. Deductions: a truncated fragment ('multi-step questions resolve in one call') that reads awkwardly after 'For a single lookup use ask_pipeworx instead,' and slight overlap with the depth parameter's schema description.

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

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

With no output schema, the description carries full responsibility for return-value semantics and delivers: findings packet composition, gaps[] and contradictions[] behavior, citation_uri fetchability guarantees, the hop field, auth requirements, timing, and depth-mode differences. For a tool of this complexity, the coverage is essentially complete; only the semantic meaning of the 'hop' field is left slightly implicit.

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

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

Schema coverage is 100%, so the schema already documents 'question' and 'depth' well, putting the baseline at 3. The description adds selection-relevant context beyond the schema: concrete example questions, the paid-plan gate on 'thorough,' and per-depth latency expectations. Minor deduction for redundancy — the contradictions[] scan behavior appears in both the schema's depth description and the prose.

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?

States a specific compound verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' Actively differentiates from siblings by negating 'this is NOT open-web search' and by naming the exact output ('findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation'). An agent can confidently distinguish this from ask_pipeworx and compare_entities without opening any schema.

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

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

Provides explicit when-to-use and when-not-to-use guidance with named alternatives: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx instead,' and 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' Also gates the paid 'thorough' depth explicitly. Nothing is left to inference.

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/openWorld/idempotent hints, the description discloses fan-out across many sources, soft-failure for the USPTO API sunset, expected empty sections (e.g., FDA products for small-molecule-only companies), and the meaning of sources_used/sources_failed. It also explains the private-company response shape. This is exceptional 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 front-loaded with trigger examples and a clear purpose, then systematically walks through return fields, failure semantics, and edge cases. Every sentence carries useful information; there is no filler or tautology despite the high level of complexity.

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

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

With no output schema present, the description carries the full burden of explaining return shape, and it does: it enumerates cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, and LEI fields. It also covers failure modes, expected empty results, and input resolution behavior, making the tool safely invokable without additional lookup.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds value with concrete examples (AAPL, 0000320193, Moderna), clarifies that type='company' and type='ticker' are interchangeable, and explains name resolution via SEC EDGAR. It mostly reinforces the schema but enriches it with usage-level clarity.

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

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

The description opens with concrete trigger phrases and clearly states the core action: producing a full cross-source profile of a US public company in one parallel call. It names the resource types (SEC EDGAR, XBRL, etc.) and differentiates itself from chaining single-pack lookups, so an agent can tell it apart from narrower tools.

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

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

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view. It also gives the accepted input shapes (ticker, CIK, name), notes that private companies yield resolved:false rather than a failure, and implies people/places are out of scope with 'person/place coming soon.'

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?

Despite all annotation hints being false, the description discloses rich behavioral details: rate limiting ('5 per identifier per day'), cost ('free; doesn't count against your tool-call quota'), the claim_token workflow for following up on reports, and the fact that 'signal directly affects roadmap.' This fully compensates for the lack of annotation hints.

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

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

The description is longer than typical but every sentence carries useful information. It is front-loaded with the core purpose, then provides usage conditions, exclusions, token handling, and rate limits in a logical order. It slightly over-delivers on background context (e.g., 'team reads digests daily') but remains focused and readable.

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

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

This is a nuanced tool with nested context objects, enum types, and no output schema. The description explains the return value (claim_token), how to use it for follow-up, rate limits, and scope boundaries, making it complete for an agent to decide when to invoke the tool and how to interpret results. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifying that it should be used 'with no other arguments.' It also implies that filing without an account returns a claim_token, which supplements the schema's parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool's purpose and differentiates it from sibling tools like ask_pipeworx or discover_tools, which are for querying, not feedback.

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

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

The description explicitly enumerates when to use the tool: for bugs ('wrong/stale data'), feature/data gaps ('tool you wish existed'), and praise ('worked surprisingly well'). It also gives clear exclusion criteria, stating it is 'ONLY for tools served by this Pipeworx connection' and instructs users to file with the other server otherwise. This is exemplary usage guidance.

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

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

The description adds 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?

Discloses substantial behavior beyond annotations: matching is keyword/word-overlap based, `pairing_unverified` is always set, Kalshi fees are not modeled so spreads are gross, compatibility codes can be non-empty even with matched pairs, and unknown metric/legs are never paired. No contradiction with readOnly/idempotent 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 clearly structured (RESPONSE, SAFETY FIELDS, codes, counters) and front-loaded with the core purpose. It earns most of its length given the tool's complexity, though it is arguably longer than strictly necessary.

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

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

With no output schema, the description fully covers return semantics: raw leg prices, top_spreads_pp, compatibility fields, per-entry flags, skipped counters, temporal alignment, and the fees caveat. It even warns about false expectations from pre-mapped topics, leaving an agent well equipped to call and interpret results.

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

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

Even though the schema already describes each parameter, the description adds crucial interaction semantics: both modes run the same token-overlap matcher, explicit parameters override topic mapping, and the same disclosures apply in either mode. This goes well beyond the schema's per-field text.

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 states a specific resource and action: cross-venue spread between Kalshi and Polymarket for the same resolving question, with two concrete modes. It is clearly distinct from single-venue siblings like polymarket_edges, though it does not explicitly name an alternative.

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 mode-selection guidance: use `topic` for pre-mapped macro shortcuts, use explicit ticker/slug pairings for custom comparisons, and warns that pre-mapped topics are not necessarily tradeable. It does not explicitly contrast with sibling tools such as polymarket_arbitrage.

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?

The description goes far beyond the read-only and idempotent annotations by disclosing multi-source fallbacks (EDGAR, GLEIF, OpenFIGI), graceful degradation if external sources fail, how ambiguity is handled (returns figi_candidates, asserts nothing), explicit unresolved identifiers, and edge cases like ISIN-to-LEI mapping. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but every sentence delivers distinct value—usage trigger, supported types, cross-source details, degradation behavior, and parameter nuances. It is well-organized with clear topic breaks, and the most actionable guidance ('Use FIRST...') appears up front.

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

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

Despite having no output schema, the description proactively explains what the tool returns (identifiers, labels, unresolved, figi_candidates) and how it handles failures. With a complex multi-endpoint tool, this level of detail ensures an agent knows what to expect and how to react. Nothing essential is missing.

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 critical usage semantics beyond field definitions: explains the exact input format for company names (e.g., issuer as printed, not the full noun phrase), gives examples (AAPL, CIK, ISIN), and warns about trailing security-class words. This significantly helps an agent call the tool correctly.

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

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

The description states a specific action ('resolve a user-spoken NAME to the canonical/official identifiers'), names the resource types (company, drug), and clearly distinguishes itself from sibling tools that profile or compare entities. It covers supported input forms and output identifiers, 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 explicitly says 'Use FIRST whenever you have a name but need an ID' and elaborates on when each entity type is appropriate. It does not explicitly state when NOT to use it or name alternative tools, but the 'FIRST' directive and clear input requirements give strong contextual guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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?

Beyond the annotations' read-only/idempotent hints, the description discloses internal routing (SEC EDGAR/XBRL for financial claims vs. grounded pipeline), the full verdict enum, and the semantic distinction between could_not_verify and unsupported. This is substantial behavioral context that helps an agent correctly interpret results and avoid misrepresenting failures as evidence.

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

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

Although longer than typical descriptions, every sentence earns its place: trigger phrases, scope, routing logic, return value specification, critical caveat, and efficiency claim. The content is front-loaded with user-facing intents and the important could_not_verify warning is clearly highlighted, making it well-structured 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, the description fully covers return values: the six verdict options, the actual value with citation, and reasoning. It also explains what could_not_verify and unsupported mean, including the verification_error structure, and describes the processing pipeline for different claim types. This makes the tool sufficiently complete for an agent to invoke and interpret correctly.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions for claim (including an example) and tolerance_pct (range, override, default, cap). The tool description adds no new parameter-level detail beyond referencing 'exact percent-delta math,' so the schema bears the semantic load and the 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 concrete trigger phrases ('fact check', 'verify the claim', 'true or false') and explicitly states the core function: natural-language claim verification against authoritative sources. It clearly differentiates from sibling tools by scoping to claim verification and even notes it replaces 4–6 sequential calls, making its 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 provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains how different claim types are routed and includes a crucial caller warning about interpreting could_not_verify. However, it does not name alternative tools to use instead or state when not to use this tool, so it stops short of a 5.

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