Fmp

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already cover safety, and the description adds valuable context: default model, cost implications of passing _apiKey, the per-model return structure, and the combined view. It does not mention rate limits or failure behavior, but the source of extras justifies a score above baseline yet not a full 5.

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

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

The description is three sentences, front-loaded with the main action and purpose, then concise details on models, return format, and use cases. Every sentence contributes information; no fluff or redundancy.

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

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

Given there is no output schema, the description fully explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers parameter usage, optional setup, cost implications, and use cases, making it complete for a 4-parameter tool with external API calls.

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 baseline is 3. The description adds semantic value by clarifying the default model (Workers AI Llama-3.3-70b), the relationship between models and _apiKey, and the direct billing model for Anthropic calls, which goes beyond what the schema descriptors state.

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 ('Probe one or more LLMs') and resource ('what they know about a business / brand / product / topic'), plus the outcome ('score visibility (0-100) per model'). It distinguishes itself from sibling tools like ask_pipeworx by emphasizing visibility scoring rather than question answering, and explicitly lists use cases like AI-marketing audits and competitive monitoring.

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 ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains optional setup (_apiKey for Anthropic). However, it doesn't explicitly name alternatives or state when not to use it, relying on implied differentiation rather than explicit exclusions.

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

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

Annotations already declare safe/read-only/idempotent. Description adds concrete behavior: routes across 5,529 tools, fills arguments, works on every tier, one fast call, returns citation URIs, and can route to live news. No contradiction.

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

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

Long but dense and front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'). Every sentence serves a purpose: scope, mechanism, examples, default status, and escalation paths. The structure flows from primary use to alternatives.

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?

Complex routing tool with no output schema is fully explained: domains covered, citation format, default entry point, tier behavior, and escalation conditions. The description gives enough context for an agent to know when to invoke and 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 already documents the single required `question` parameter and aliases at 100% coverage. Description supplements with concrete example questions and broad natural-language triggers, but doesn't add new parameter-level detail beyond examples.

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

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

Description clearly states it's a routing/answering tool: 'Routes the question to the right one of 5,529 tools... returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Explicit guidance: 'PREFER OVER WEB SEARCH...', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives. It lists trigger phrases and examples, plus a note about breaking news 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?

The description transparently discloses the experimental nature of the tool, including that it is the 'experimental edge' and that candidate routing improvements are enabled live whenever under test. It also clarifies the fallback behavior ('falls back to nothing — this IS a full working router'), adding context beyond the annotations about the tool's variability and reliability.

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

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

The description is concise at four sentences, with the key fact (beta version) front-loaded. It efficiently conveys the relationship to ask_pipeworx, the experimental state, and current behavior, though it could be slightly tighter without losing essential information.

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

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

The description fully covers the tool's purpose, usage context, and current state, including the absence of an active candidate and the comparison mechanism with the stable router. It also addresses the fallback behavior, making the tool self-explanatory even without an output schema.

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

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

The schema already provides 100% coverage for all six parameters, each described as an alias for question. The description adds no parameter-specific 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 clearly identifies this as a beta version of the ask_pipeworx universal router, explicitly stating it has the same 5,529 tools, arguments, and response shape as the stable version. It distinguishes itself from the sibling ask_pipeworx by mentioning candidate routing improvements, making its purpose and scope immediately clear.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide what merges. It also notes that no candidate is active right now, so it currently matches ask_pipeworx exactly, effectively telling the agent when to choose this tool over the stable alternative.

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 annotation by detailing the refusal mechanism, the exact refusal_reason enum values, the return structure (answer, evidence, confidence, source, fetched_at), and the cost implication. This fully discloses the non-answer behavior and output format, which is crucial for a grounded mode.

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 perfectly front-loaded with the core differentiator ('Hallucination-resistant') and each subsequent sentence adds a distinct fact: routing, extraction constraint, refusal reasons, use cases, cost, and alternative. Every sentence earns its place without redundancy.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It explains the return format, all refusal reasons, cost trade-offs, and when to use it. Nothing critical is left uncovered for an agent to correctly 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?

The input schema already covers 100% of parameters, with the question parameter and its aliases fully described. The description adds no extra parameter semantics beyond implying that the question is the sole input. Baseline 3 is appropriate because the schema carries the load.

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

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

The description explicitly defines the tool as a hallucination-resistant grounded answer mode, with a specific verb ('extracts the answer') and a clear resource (the tool routing across Pipeworx sources). It distinguishes itself from the sibling ask_pipeworx by emphasizing the evidence-only extraction and refusal behavior, making its 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?

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts it with the alternative: 'prefer ask_pipeworx for casual lookups.' It also discloses a cost trade-off (one extra LLM call), giving the agent clear decision criteria.

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

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

The description adds no behavioral context beyond what annotations already declare. Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) cover safety, but the description doesn't explain data scope, return format, or any limitations. It is a bare noun phrase with no behavioral insight.

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

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

While extremely short, this is under-specification rather than effective conciseness. The phrase 'Balance sheet.' contains no actionable information. The tool requires at least one parameter and should describe its purpose, but the description offers only a label.

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, no return value description, and a one-word description, the tool is entirely incomplete. Given the complexity of financial statement data, the agent has no idea what to expect from this tool or how 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?

Schema description coverage is 0%, and the description does not mention any of the three parameters (symbol, period, limit). Since the description is expected to compensate for missing schema documentation, it completely fails to provide parameter meaning or usage examples.

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 is simply 'Balance sheet.' which is a tautology of the tool name. It lacks a verb and does not specify what action is performed (e.g., fetch, retrieve, display). It provides no differentiation from sibling tools like cash_flow or income_statement.

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 given on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The description is completely silent on usage scenarios.

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

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

The description is exceptionally transparent, detailing resolver contract (match confidence, alternatives), blocking statuses (low_confidence_match, market_closed_or_inactive), wide-spread handling, cancellation-rule parsing, news fallback behavior, and safety short-circuits. This goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) and provides critical behavioral context.

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

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

The description is long but well-organized with uppercase section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY) that aid scanning. While some sentences are dense, they carry necessary detail for a complex tool. It is not overly redundant; each section adds 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?

Despite having no output schema, the description comprehensively covers response shapes (result.market, result.analysis, result.evidence), error and edge cases (low-confidence, closed markets, wide spreads), parent-event extraction, news fallback details, and cancellation risk. It leaves little ambiguity for an AI agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% and includes descriptions for all three parameters, but the tool description adds substantial meaning: it explains the accepted formats for 'market' (slug, URL, question text), clarifies the depth parameter semantics (quick vs thorough, default thorough), and details the trade-offs of include_raw (response size, when to use). This enhances the schema beyond 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 purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and differentiates from siblings by focusing on bet research with Pipeworx integration and category classifiers.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed guidance on handling specific situations (e.g., 'Check this before sizing sports/esports/event-occurrence bets' for cancellation rules), which helps the agent decide appropriate invocation.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: it specifies the data source (Financial Modeling Prep), restricts to US-listed tickers, names the available periods (annual/quarterly), and enumerates the exact data fields returned. This gives agents a rich understanding of the tool's scope and output without needing to invoke it.

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, front-loads the core purpose, and delivers detail efficiently. It avoids redundant phrasing and every sentence contributes meaningful information, making it 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?

Given the simplicity of the schema (3 params, no output schema), the description covers the main purpose, key data fields, period options, and use cases. It omits clarification of the 'limit' parameter, but overall it is sufficiently complete for an agent to select and invoke the tool effectively.

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

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

With zero schema description coverage, the description compensates for two of three parameters: 'symbol' is implicitly defined as a US-listed ticker, and 'period' is explicitly stated to accept annual or quarterly. However, 'limit' remains unexplained, leaving a gap in 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 identifies the tool as a cash-flow statement from Financial Modeling Prep, enumerates specific financial metrics (operating, investing, financing activities, free cash flow, capex, net change in cash), and notes it targets US-listed tickers. This specificity distinguishes it from sibling tools like balance_sheet and income_statement.

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

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

The description provides explicit use cases ('Use for fundamental analysis, DCF inputs, cash-flow valuation'), giving clear contexts for when to apply the tool. However, it does not explicitly mention alternatives or exclusions, so it misses the 'when-not-to-use' aspect of a perfect score.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds concrete behavioral details: pulls LATEST 10-K revenue/net income/cash/long-term debt from SEC EDGAR/XBRL for companies, FAERS counts for drugs, off-calendar fiscal year handling, sorting by primary metric, and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is dense but every sentence serves a purpose: trigger phrases, tool capability, type-specific data, sorting behavior, output format. It is front-loaded 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?

The tool has no output schema, but the description explains the output shape (paired data + pipeworx:// citation URIs), covers edge cases (off-calendar fiscal years), and gives entity count limits. Given the moderate complexity, this is sufficiently complete.

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

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

Input schema covers both parameters with enums and descriptions, so baseline is 3. The description enhances meaning by specifying what type='company' vs 'drug' actually retrieves and provides examples like AAPL Sep, NVDA Jan to illustrate fiscal year handling.

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 side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete trigger phrases. It distinguishes from sibling tools like balance_sheet or income_statement by explicitly stating 'ALWAYS PREFER over sequential single-pack lookups when 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?

It provides explicit when-to-use guidance with examples like 'Compare X and Y' and 'rank these companies', and states ALWAYS PREFER over sequential lookups. It also notes that it replaces 8–15 sequential lookups, indicating when this tool is more efficient.

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

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

Annotations only declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail: account/payment requirements, parallel decomposition, findings packet structure with evidence/confidence/source/fetched_at/citations, explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting instead of head-truncation, hop field and citation_uri fetchability, and latency expectations. 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 exceptionally dense—every sentence adds a distinct point. It front-loads the account requirement, then purpose, alternatives, behavioral details, and edge cases. The structure is logical and scannable, though the length might be intimidating. Still, for a complex tool with no output schema, the richness justifies the size.

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 explains return values (findings packet with verbatim evidence, confidence, source, fetched_at, stable citation), the gaps[] and contradictions[] arrays, the hop field, and the resolvable citation_uri. It also covers time expectations, account prerequisites, alternatives, and known edge cases like breaking news, making it comprehensive for the tool's complexity.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions. The description adds value by providing example question types, reiterating that broad/multi-part questions are acceptable, and elaborating on depth's behavioral implications (e.g., second-hop gap recovery, thorough's paid plan and iterative lead-chasing). While the schema already covers most, these examples and contextual nuances push it slightly above the baseline.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, making the unique purpose unmistakable.

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

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

The description offers explicit when-to-use and when-not-to-use guidance: it requires an account (and alternatives for non-signed-in users), recommends ask_pipeworx for single lookups and for breaking news/open-web topics, and states it is best for broad/multi-part structured-data questions. These clear exclusions and named alternatives fully satisfy the dimension.

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

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

The description adds no behavioral context beyond the annotations. Annotations already declare readOnly, openWorld, and idempotent, but the description doesn't mention what the tool returns, whether there are pagination limits, or how 'delisted' is defined. It relies entirely on annotations for safety, yet provides zero additional transparency about runtime 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?

While the description is extremely short, it is under-specified rather than concise. The phrase 'Delisted companies' adds no value beyond the title and fails to convey necessary information. It could be expanded to a meaningful sentence without waste.

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

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

The tool has no output schema, and the description provides no information about the result structure, sorting, date filtering, or any other context needed to use the tool effectively. Given the complexity of financial data and the existence of many sibling tools, this description is completely inadequate.

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 description coverage is 0%, and the description does not explain the 'limit' parameter. The only parameter is a number with no description, and the tool description gives no hint about its meaning or constraints. This leaves the agent unable to understand how to set an appropriate value.

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

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

The description is 'Delisted companies,' which simply restates the tool name/title without a verb or clarifying action. It doesn't specify what operation is performed (e.g., 'list' or 'retrieve'), making it a tautology. This fails to distinguish from sibling tools like 'ipos_calendar' that might also deal with company lists.

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 about when to use this tool versus alternatives. There is no mention of use cases, exclusions, or alternative tools, despite a large list of sibling tools such as 'historical_price' or 'profile' that might overlap.

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 and idempotent behavior. The description adds valuable behavioral details: it explains that the tool returns top-N relevant tools with full schemas and curated examples, and that results are immediately callable (no second schema lookup). This goes beyond the annotations and sets accurate expectations for the response format.

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

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

The description is structured in three sentences, front-loaded with the core purpose. It lists example domains and return characteristics. While slightly longer than minimal, every sentence carries useful information and there is no redundant 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?

The tool has no output schema, but the description clearly explains the return value: top-N tools with names, descriptions, and full input schemas. It also addresses a potential need (no second schema lookup). Given the discovery-related complexity and reasonable length, the description is complete for this context.

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

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

Schema coverage is 100% with descriptions for all parameters, including aliases for 'query'. The description reinforces the natural-language intent of the query parameter and mentions 'top-N' aligning with the 'limit' parameter, but the schema already conveys this information. Since the description does not add substantial semantic details beyond the schema, 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 a specific verb+resource: "Find tools by describing the data or task." It clearly differentiates this meta-tool from sibling data-lookup tools by focusing on discovering other tools, listing many domains. 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 states when to use the tool: "Use when you need to browse, search, look up, or discover what tools exist." It also adds directive guidance: "Call this FIRST when you have many tools available and want to see the option set," which distinguishes it from directly calling a specific tool. This provides clear usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about the FMP backend limitation (market-wide only) and the local filtering behavior, plus that the response includes the searched window. 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?

Three concise sentences: the first states purpose, the second explains usage, the third adds a behavioral nuance. Every sentence earns its place with no waste.

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 core functionality and even notes the response includes window search information. However, it omits explanation of the from/to date parameters and the overall output structure, leaving gaps for an agent to fully understand the tool's interface.

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?

Only the symbol parameter has a schema description, and the description clarifies its optionality. However, the from and to parameters are not explained in the description, leaving their format and semantics ambiguous. With schema coverage at only 33%, the description should compensate but does not.

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

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

The description clearly states the tool provides 'upcoming and recent earnings dates with EPS and revenue estimates', and explains the two modes of use (with or without symbol). This differentiates it from sibling calendar tools like economic_calendar or ipos_calendar.

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 to pass a symbol for one company or omit it for the market-wide calendar, giving clear usage context. However, it does not mention alternatives or when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the valuable context that the tool is paid, which is a behavioral trait not captured by annotations. However, it does not disclose any other behaviors like date-range filtering or output limitations.

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

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

The description is extremely brief, almost a fragment. While it is concise and front-loaded with the key topic, it under-specifies the tool's functionality. The 'paid' caveat is useful but does not justify the lack of a proper sentence structure.

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 low complexity (two optional date parameters) and no output schema, the description should at least state that the tool returns economic events over a date range. It fails to do so, leaving the agent to infer from the name and schema example. The description is incomplete for reliable invocation.

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

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

Schema description coverage is 0%, and the description does not compensate. The 'from' and 'to' parameters are only shown in the schema example without any explanatory text, and the description makes no mention of them, leaving their meaning and format entirely implicit.

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

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

The description identifies the resource as 'Economic events' and notes it is paid, but lacks a clear verb like 'list' or 'get'. It distinguishes from sibling calendar tools by subject matter (economic vs earnings/IPOs), but the purpose is understated and vague.

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

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

No guidance is provided on when to use this tool versus alternatives such as earnings_calendar or ipos_calendar. The only qualifier is 'paid', which hints at cost but does not explain appropriate usage contexts or 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?

The description adds no behavioral context beyond the annotations. Annotations indicate a safe read-only, idempotent operation, but the description does not explain what data is returned, any limitations, or scope. With zero description, the agent gets no additional transparency.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It does not earn its place because it provides no useful information beyond the title.

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, three parameters, and zero description coverage, the description is completely inadequate. An agent cannot determine what the tool does, when to use it, or how to call it effectively.

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

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

Schema description coverage is 0%, and the description gives no information about the parameters (symbol, period, limit). The description fails entirely to compensate for the missing schema context.

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 is merely the tool name 'Enterprise value.' with no verb or resource specified. It does not distinguish this tool from its many siblings and provides no indication of what action it performs.

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?

There is no guidance on when to use this tool versus alternatives like 'balance_sheet', 'quote', or 'key_metrics'. No context, prerequisites, or exclusions are provided.

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 specific behavioral details: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns up to 5 filings with URIs; fundamentals from latest 10-K sorted period_end desc; patents via USPTO with a sunset date and soft-fail behavior; news via GDELT→GNews fallback. This goes well beyond the annotations.

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

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

The description is long but every sentence carries substantive information: usage examples, preference directive, data source list, output summary, input constraints, and a known API deprecation. It's well-structured with semicolons to separate the output fields and front-loaded with the most important usage case.

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

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

The tool has no output schema, so the description must explain return values—it does, listing cik, company_name, filings, fundamentals, patents, news, and LEI, plus specifics like the 5-filing limit and period sorting. It also notes a known failure mode (patents sunset) and fallback, making it highly complete for an agent.

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

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

The input schema already documents both parameters fully (type = 'company' only; value = ticker or zero-padded CIK, names not supported). The description repeats this almost verbatim but adds concrete examples and the resolve_entity pointer. With 100% schema coverage, the description adds marginal value, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: building a full cross-source profile of a US public company in one parallel call. It uses specific action verbs ('research', 'brief', 'profile') and a specific resource (US public company), and distinguishes it from chaining separate SEC/XBRL/news lookups.

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

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

Explicitly says to prefer this over chaining single-pack lookups when a holistic view is needed. Also provides a clear exclusion: names are not supported; use resolve_entity first if only a name is known. This gives the agent concrete decision criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds the useful 'paid' caveat, which is not captured in annotations, but it does not disclose other behavioral traits like output format, rate limits, or failure modes. It does not contradict annotations.

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

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

The description is very short and front-loaded with no filler words, which is concise. However, it is just a noun phrase with a parenthetical, not a complete sentence, and it sacrifices substance for brevity.

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 needed to explain what the tool returns, but 'ETF holdings' alone does not specify whether it returns constituents, weights, prices, or other details. The 'paid' caveat is helpful, but overall the description is too sparse to be complete for a tool with no structured output definition.

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

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

With schema description coverage at 0%, the description needed to explain the 'symbol' parameter but does not. The schema itself only provides a type and an example ('SPY'); the description adds no meaning about what symbol means, accepted formats, or how it relates to ETFs.

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, 'ETF holdings (paid),' names the resource but lacks a verb such as 'retrieve' or 'list' to specify an action. It is essentially a restatement of the tool title and does not explicitly clarify what the tool does beyond referring to ETF holdings data.

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

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

No guidance is provided about when to use this tool, what prerequisites apply (e.g., a paid subscription), or how it differs from related sibling tools like key_metrics, quote, or profile. The description gives no context for choosing this over alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral context, such as return format, pagination, or specific growth metrics included. While the annotations cover safety, the description fails to clarify what 'growth rates' entails, leaving significant ambiguity.

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

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

The description is extremely short (two words), but this is under-specification rather than conciseness. It lacks structure and substantive content. While it is front-loaded, it does not earn its place as it conveys almost no useful information.

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

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

Given the tool has three parameters, no output schema, and zero schema description coverage, the description is grossly inadequate. It does not explain what data is returned, how parameters interact, or any limitations. It is incomplete even for a simple lookup 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 description coverage is 0%, and the description does not explain any of the three parameters (symbol, period, limit). There is no mention of what 'period' values are valid, what 'limit' controls, or that 'symbol' is required. The example in the schema helps, but the description itself provides no 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 'Growth rates.' is a noun phrase that identifies a resource but lacks a verb indicating an action. It is slightly more specific than a pure tautology but does not clearly state what the tool does, such as retrieving or calculating growth rates. It also does not differentiate itself from sibling tools like 'ratios' or 'key_metrics'.

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?

There is no guidance on when to use this tool versus alternatives. The description provides no context, prerequisites, or exclusions. It is completely silent on use cases, making it impossible for an agent to know if this is the right tool for a given task.

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 already include destructiveHint=true and readOnlyHint=false, and the description does not contradict them. The description adds slight context by mentioning 'clear sensitive data' and 'agent saved earlier,' but it does not disclose additional behavioral traits such as irreversibility or error handling beyond what annotations imply.

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

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

The description is concise, front-loaded with the core action, and each sentence adds value: the action, the usage timing, and related tools. No filler or redundant information.

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

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

For a one-parameter destructive tool with idempotentHint and destructiveHint annotations, the description plus schema fully support tool selection. The usage context and pairing with related tools make it complete even without an output schema.

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

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

Schema description coverage is 100%, so the parameter is already well-documented. The description says 'by key' but adds no meaning beyond the schema's 'Memory key to delete.'

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes this tool from sibling tools like remember and recall by focusing on deletion, making its purpose unambiguous.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not give explicit when-not-to-use guidance or alternative tools, but the context is clear and it pairs with remember and recall.

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, and the description adds non-redundant process details: fetching the page, extracting title/description/key links, and emitting a markdown blob. The output format is explicitly stated as a single text blob ready for site-root placement, which complements the safety metadata. No contradiction exists between the description and annotations.

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

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

The description is compact—two sentences including a short 'Useful for' list—and front-loads the main purpose and output. No filler words or repeated schema details; every phrase contributes to understanding.

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

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

Given the tool's modest complexity and strong annotations, the description covers purpose, process, output shape, and likely use cases. It doesn't explain error cases or JS-render caveats, but for a read-only generator this is sufficient; the output is described even though no output schema exists.

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

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

Schema coverage is 100%: both url and max_links have descriptions. The tool description reinforces that url is the site to summarize and mentions 'any URL' but does not add details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific action ('Generate a production-ready llms.txt file') and clearly states the resource (llms.txt) and purpose (indexing for AI crawlers). It distinguishes the tool by naming the output format and use cases (client sites, own projects, competitor auditing), so it doesn't rely on the title alone.

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 'Useful for:' contexts—indexing a client site, drafting for own project, or auditing competitors—which tells when to invoke it. It does not explicitly name sibling alternatives or state when not to use it, so it falls short of the top tier but gives clear situational 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the granularity of the data (daily EOD) but does not disclose other behaviors such as date range handling, return ordering, or pagination, so it adds only minimal value beyond the annotations.

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

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

The description is only two words, 'Daily EOD history,' which is extremely concise and front-loaded. While it is a sentence fragment and perhaps under-specified, it efficiently conveys the core idea with no wasted words.

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

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

The description is too sparse for a tool with three parameters and no output schema. It doesn't explain return values, date range behavior, or whether prices are adjusted, leaving significant gaps for an agent trying 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 has 0% description coverage for its three parameters, and the description does not explain 'to', 'from', or 'symbol'. While the parameter names are somewhat self-explanatory, the description fails to specify date formats, inclusivity, or defaults, so it does not compensate for the lack of parameter documentation.

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

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

The description states 'Daily EOD history,' which clearly indicates the tool provides historical end-of-day price data, and the term 'Daily' distinguishes it from sibling tools like 'intraday.' However, it lacks an explicit verb such as 'retrieves' or 'gets,' making it a clear but terse noun phrase.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that it should be used for historical daily data while 'intraday' is for intraday data or that 'quote' is for current prices. There is no when-to-use or when-not-to-use information.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is known. However, the description adds zero behavioral context, such as what data is returned, how periods are handled, or any limitations. It merely repeats the name.

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

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

The description is very short, which is concise, but it is under-specified. It provides no useful information beyond the title. This is not effective conciseness; it is a lack of specification.

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 a 3-parameter tool with no output schema and no parameter descriptions, the description is completely inadequate. It does not explain the purpose, the meaning of parameters, or the expected output, making it nearly impossible for an agent to select and invoke the tool correctly.

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

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

The input schema lists three parameters (limit, period, symbol) with no descriptions, and schema description coverage is 0%. The description does not mention any parameters, leaving the agent without any hints about their meaning, allowed values, or required format beyond the raw schema types.

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 is 'Income statement.' which simply restates the title. It lacks a specific verb and does not explain what the tool does with the resource (e.g., retrieves, lists, generates). It also does not distinguish itself from sibling tools like balance_sheet or cash_flow.

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?

There is no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are provided. A user would have no idea that this tool is for financial statement data or when to choose it over similar financial 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read. However, the description adds no behavioral context beyond the 'paid' note, which is a cost constraint rather than operational behavior.

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

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

The description is extremely short but under-specifies the tool's purpose and usage. It is not concise in the sense of adding value; it is a bare label that fails to earn its place.

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

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

For a tool with three parameters and no output schema, the description is entirely insufficient. It does not describe return format, filtering behavior, or typical usage, making it impossible for an agent to invoke correctly without external knowledge.

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

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

The schema has 0% description coverage, and the description does not mention or explain the parameters 'page', 'limit', or 'symbol'. It provides no semantic assistance beyond the bare schema structure.

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 'Insider trading (paid)' names the domain but lacks an action verb such as 'get' or 'list', making it read as a label rather than a function. It does not distinguish this tool from sibling data-retrieval tools like 'institutional_ownership' or 'key_metrics'.

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?

There is no guidance on when to use this tool compared to alternatives. No context, prerequisites, or exclusions are provided.

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

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

Annotations already declare it read-only, idempotent, and non-destructive. The description adds the 'paid' qualifier, which is a useful behavioral trait beyond annotations, but does not disclose other important behaviors like return format or error conditions.

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

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

The description is very short and to the point, but it borders on under-specification. It is not verbose, but it lacks a full sentence and does not explain the tool's purpose sufficiently. The two pieces of information (topic and paid status) are useful, but the overall structure is minimal.

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

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

Despite the simple parameter set and strong annotations, the description does not explain what data is returned or how to use the symbol parameter. The example in the schema provides some context, but the description alone is insufficient for a user to understand the tool's output or behavior.

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

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

The schema has one required parameter 'symbol' with no description, and the description does not mention it at all. With schema coverage at 0%, the description was expected to compensate but provides no parameter semantics beyond the example in the schema.

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

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

The description identifies the resource (institutional ownership) and notes it is paid, but lacks an explicit verb like 'get' or 'retrieve'. It is more than a tautology and is distinguishable from sibling tools, but does not fully state the action performed.

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

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

No guidance on when to use this tool or which alternatives might be better. The description only states the topic and that it is paid, with no mention of use cases or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, covering the safety profile. The description adds the 'paid' context, which is a useful behavioral caveat. However, it does not elaborate on subscription requirements, rate limits, or return format, so the added transparency is limited.

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

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

The description is extremely concise, consisting of only four words: 'Intraday OHLC (paid)'. It is front-loaded and contains no wasted words. However, it borders on under-specification, as it omits important operational details.

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

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

Given the simple two-parameter tool with annotations and schema examples, the description provides a brief but somewhat adequate overview: intraday OHLC data, paid. However, it does not specify valid interval values or what 'paid' entails, so an agent might still be uncertain about correct invocation.

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

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

The schema has zero description coverage for parameters, and the description does not explain what 'symbol' or 'interval' mean. The schema examples provide some hints, but the description itself adds no parameter meaning. This leaves the agent to infer from names and examples, which is insufficient.

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 'Intraday OHLC (paid)' clearly indicates the tool returns intraday OHLC data, which is specific enough to distinguish it from sibling tools like historical_price or quote. However, it lacks an explicit verb like 'get' or 'retrieve', making it a noun phrase rather than a clear action statement.

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 about when to use this tool versus alternatives such as historical_price or quote. The only extra hint is that it is 'paid', which is a cost constraint rather than a usage guideline. There are no exclusions or alternative recommendations.

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 as read-only, idempotent, and non-destructive, which covers the safety profile. The description adds the 'paid' qualifier, indicating a potential access or cost restriction not captured by the annotations. However, it does not elaborate on what 'paid' means or what the calendar returns, so the disclosure is minimal.

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

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

The description is under-specified rather than concise. It consists of a single phrase that does not earn its place because it adds little beyond the tool name. A concise description would convey useful information in few words, but this one omits essential details about parameters, output, and usage.

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 calendar tool with no output schema and two undescribed parameters, the description should explain the return format, date filtering, and any restrictions. The description only says 'IPO calendar (paid),' which does not clarify what data is returned, how to specify a date range, or how this differs from earnings_calendar and economic_calendar. The lack of output schema makes this a significant gap.

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

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

The schema has two string parameters ('to' and 'from') with no descriptions, resulting in 0% schema coverage. The description does not mention these parameters at all, failing to compensate for the lack of schema documentation. The only hint is the example in the schema, which is not referenced or expanded in 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 'IPO calendar (paid)' is essentially a tautology that restates the tool's name and title. It identifies the domain (IPOs) but does not specify a verb or action, leaving the agent to infer that it lists or shows IPO events. It differentiates only slightly from sibling calendars like earnings_calendar and economic_calendar by naming IPOs.

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. The description gives no context about the date range parameters, typical use cases, or exclusions (e.g., 'use this for upcoming IPOs'). It also does not mention any alternatives, leaving the agent without a basis for tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no behavioral detail beyond a vague 'TTM' scope, failing to disclose what data is returned or any limitations. It does not contradict annotations but adds no value.

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

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

The description is only four words, which is not conciseness but under-specification. It does not earn its place because it adds almost no information beyond the tool name. A useful description would be slightly longer but with substantive 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?

For a financial metrics tool with no output schema, no parameter explanations, and a minimal description, this is completely inadequate. It fails to clarify what 'key metrics' are included, the structure of output, or how TTM is calculated, leaving the agent to guess how to use and interpret results.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any of the three parameters (symbol, limit, period). There is no mention that symbol is required or what period refers to. This leaves the agent with no guidance on how to correctly invoke the tool.

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 'TTM key metrics' is essentially a tautology of the tool name and title, adding only 'TTM' (trailing twelve months) as context. It lacks a verb and does not specify what the metrics are or how they are presented, so the purpose is only vaguely implied.

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

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

No usage guidance is provided. The description does not mention when to use this tool versus sibling tools like ratios, financial_growth, or cash_flow, nor does it give any context on symbol, period, or limit usage. There is no alternative or exclusion information.

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 context by specifying the exact return fields and that it lists only the caller's subscriptions, which is beyond the annotation hints. No contradictions.

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

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

The description is two sentences, front-loaded with the primary purpose, then provides usage guidance. Every word 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?

For a simple read-only list tool with no output schema and clear annotations, the description covers the main purpose, the return fields, and the intended use cases. It is complete 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?

The schema has 100% coverage for the single parameter 'include_inactive' with a clear description. The tool description adds only a slight nuance ('active subscriptions') but does not significantly enhance the schema's parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It uses a specific verb ('list'), names the resource ('subscriptions'), and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing rather than creating or removing.

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 tells when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies the alternatives (subscribe/unsubscribe) and gives clear context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and mutation concerns. The description adds that it is a feed of announced deals, but does not disclose behavior like pagination limits or return format. Given annotation coverage, this is adequate but not rich.

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

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

The description is two sentences long and immediately communicates the tool's purpose and use cases. It is front-loaded with the core function and contains no superfluous information.

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

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

The tool is simple with one optional parameter and no output schema. The description explains the data content (acquirer, target, value, date) and use cases, but it does not describe how the 'page' parameter affects results or what the response structure looks like. This is a noticeable 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?

There is one parameter, 'page', with no description in the schema (0% schema coverage). The description does not mention this parameter at all, leaving its purpose and usage entirely undocumented. The description fails to compensate for the lack of schema 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 what the tool does: it provides a recent M&A activity feed with announced deals including acquirer, target, value, and date. It also gives specific use cases, which helps distinguish it from sibling financial data tools, 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?

The description gives explicit use cases: 'who did $TICKER acquire', 'recent deals in sector X', and deal-flow monitoring. This provides clear context for when to use the tool, but it does not mention when not to use it or direct users to an alternative tool.

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

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

Annotations are all false and therefore uninformative, so the description carries the burden—and it delivers. It discloses that filing returns a claim_token for later status checks, that feedback is read daily by humans, that the tool is rate-limited to 5 per identifier per day, and that it's free and doesn't count against quota. No contradictions with annotations.

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

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

The description is front-loaded and logically organized: purpose first, then usage triggers, exclusions, follow-up token mechanics, and rate/quota. Each sentence adds distinct value—no filler—even though it's longer than typical, 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?

Given no output schema and unhelpful annotations, the description compensates fully: it covers what the tool does, when to use it, what to avoid, the claim_token round-trip, rate limits, and quota behavior. It leaves no material gaps for a feedback submission 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 description coverage is 100% with clear per-parameter semantics (type enum, context object, message length, claim_token usage). The description reinforces the claim_token flow but does not add new parameter information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types and distinguishes itself from sibling data/research tools by framing this as a reporting channel, not a data query.

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 states concrete triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an explicit exclusion for tools from other MCP servers and tells users to file with that server instead, plus advises against pasting end-user prompts. This is exemplary alternative-selection 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 annotations (readOnlyHint, openWorldHint, etc.), the description adds valuable behavioral context: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, and caching behavior, enriching the tool's operational understanding.

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

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

The description is well-structured with a clear opening statement and enumerated use cases. Every sentence earns its place, providing high information density without unnecessary 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?

The tool is simple (1 optional parameter) and the description fully covers what it returns, caching behavior, and data privacy. No output schema exists, but the return format is explicitly described ('top tools, top packs, and total call volume'), making it complete for the intended use.

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

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

The schema already has 100% coverage with descriptive text for the 'window' parameter, including default and trade-offs. The description mentions windows but does not add beyond the schema's explanation, 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's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses a specific verb and resource, and distinguishes itself from siblings like discover_tools by focusing on agent call trending.

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

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

The description provides three explicit use cases, such as 'discovering what data sources are hot for current events' and 'confirming a popular tool is the canonical choice.' While it gives clear context for when to use it, it does not mention when not to use it or name specific alternative tools, so it lacks full exclusionary 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 readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: scanning scope (~200 markets by weekly volume), internal filters (Jaccard ≥0.30, placeholder threshold >20%), and the fill-check caveat (realizable_edge_pp ≤ 0 means do not trade). No contradictions with annotations.

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

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

The description is long but every section earns its place: first sentence states the core function, then each mode is delineated with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the main purpose and structured for quick scanning. No redundant or filler 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 complex tool with three modes and no output schema, the description is remarkably complete. It explains the response structure (opportunities[], partition_check, fill check fields), addresses failure/skip conditions (zero similarity, placeholder filtering), and cross-references polymarket_fill_risk for custom sizing. The agent has all necessary context to decide when and how to invoke it.

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

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

The schema already covers both parameters with 100% coverage, but the description goes far beyond by explaining the semantics of each mode: event accepts slugs or full URLs and walks child markets; topic accepts seed questions and searches related events. It also clarifies the output context for each parameter. This adds significant meaning over the schema.

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

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

The description opens with a precise statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific resource (Polymarket), the action (find arbitrage), and the method (monotonicity violations + partition-sum checks), clearly distinguishing it from siblings like polymarket_edges, polymarket_fill_risk, and polymarket_kalshi_spread.

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

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

Usage is explicit: three modes are spelled out (no args for trending_scan, event for per-event partition_check, topic for cross-event scan), with concrete examples and a recommendation ('event (recommended for a specific market)'). It also states when to use an alternative ('For custom sizing use polymarket_fill_risk') and explains that cross-event mode catches patterns single-event misses.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes far beyond by detailing response structure (by_segment, fed_candidates, _diagnostics), model families, edge-computation specifics (slippage, Kelly caps, per-sport α values), caching behavior ('Cached 1h at the KV level keyed on all knobs'), and warnings like the 24h-move alert. This provides rich behavioral context without contradicting the annotations.

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

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

The description is dense and long, but every sentence earns its place, covering purpose, models, output structure, knobs, diagnostics, and caching. It is front-loaded with the core purpose. However, it is presented as one massive unbroken paragraph, which hurts readability; better structuring into bullets or sections would improve conciseness.

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

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

There is no output schema, but the description thoroughly explains response top-level fields, per-opportunity attributes, diagnostics for empty segments, Fed candidate exclusion rationale, and caching behavior. This is complete for an agent to know what to expect and how to interpret results, despite 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?

The schema has 100% coverage with detailed descriptions for all 9 parameters, including nuanced explanations (e.g., min_partition_leg_kelly's interaction with partition arbs). The tool description re-summarizes some knobs but does not add meaningful semantic information beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the load.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on model-driven edge detection rather than pure arbitrage. The additional context ('Built for what should I bet on today') reinforces the purpose.

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

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

The description provides a clear usage scenario ('discover opportunities without paging hundreds of markets') and explains the tradeable-edge filters (knobs) that adjust results. However, it does not explicitly mention when to avoid this tool or name alternatives like polymarket_arbitrage for pure arbitrage cases, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond these: snapshot cache-miss behavior causing gaps, the 60-day snapshot TTL bounding history depth, and that decay is computed from daily closes not intraday data. This is rich, non-obvious 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 a dense paragraph but well-structured with clear labels (Args, RESPONSE, LIMITS). It front-loads the core purpose and every sentence carries meaningful information. It is longer than minimal but justified by the complexity of the tool and the lack of an output schema.

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

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

With no output schema, the description fully documents the return structure: tracked[], expired[], and snapshot_dates[], including field semantics, trend categories, and caveats about data gaps and history depth. It is complete for an agent to invoke the tool and interpret results without 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?

The input schema already provides 100% coverage of both parameters (days and window) with defaults, clamps, and enum-like values. The description restates defaults and adds the 'snapshot family' framing, but this is marginal value beyond the schema's existing descriptions, so a 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 defines the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' with a specific verb and resource. It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on time-series persistence and decay rather than current edges.

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

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

The description provides strong usage context: it contrasts a fresh wide edge with a 3-week-old wide edge to illustrate when the tool adds value. It does not explicitly name alternatives or state when not to use it, but the context makes the intended use case clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details behavior: walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains verdict values, and highlights the risk of partial basket fills converting an arb into unhedged directional risk. This is rich behavioral context that annotations don't provide. No contradiction with annotations.

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

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

The description is long but front-loaded with the purpose and then logically structured by mode, usage, and return details. Every sentence has purpose—no fluff. Given the tool's two modes and extensive output list, the length is justified; however, it could perhaps be more scannable with bullets or shorter sentences, so not a perfect 5.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers all key aspects: required input (one of market/event), side defaults, size interpretations, return values for both modes, and risk warnings. An agent would have enough context to invoke this tool correctly and interpret results, even without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantics by requiring one of `market` or `event` and clarifying the size_usd interpretation in each mode ('max spend on buys, target proceeds on sells' for single-market; 'settlement notional S' for basket). It also explains the default side for basket mode via partition sum, which complements 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 opens with a clear verb-resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly names the two modes (single-market and basket) and lists the return fields, making it easy to understand exactly what the tool does. It also distinguishes itself from siblings by referencing polymarket_arbitrage and polymarket_edges as the tools to use with this one.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical edge is not capturable on thin books; partial fills create unhedged positions), giving a concrete condition and alternatives implicitly (before using the sibling tools). Additionally, it distinguishes between single-market and basket modes with clear instructions for each.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description goes far beyond this by disclosing behavioral nuances: how compatibility_warning fires, what temporal_alignment means, what skipped_cross_type/subtype represent, and the current limitation that most pre-mapped topics return warnings. This is rich contextual information about edge cases and output semantics, fully leveraging the description's job beyond structured metadata.

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

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

The description is longer than many, but it is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence conveys distinct information. It front-loads the core purpose and then dives into details. The length is justified by the tool's complexity, and the structure aids skimming, so it earns a 4 rather than a lower score.

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 there is no output schema, the description must explain return values and conditions. It does so thoroughly: response includes leg-by-leg prices, matched spread, compatibility_warning with two specific trigger cases, temporal_alignment, and skipped_cross_type/subtype counters. It also addresses current limitations and the meaning of alignment. This is a complete and self-sufficient explanation for a complex tool.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining the interplay between modes: topic is a shortcut, and explicit event ticker/slug override the topic-mapped sides. It also provides a concrete list of supported topics and hints at the structural differences between venues (e.g., range_bucket vs cumulative_threshold). This goes beyond the schema's bare 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 precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It states the tool's function explicitly (comparison of prices across two prediction markets) and differentiates from siblings like polymarket_arbitrage by emphasizing the cross-venue aspect. It also clearly describes two operational modes, leaving no ambiguity about what the tool does.

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

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

The description explains two usage modes (topic shortcuts and explicit ticker/slug pairing) and includes cautionary guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today.' This gives users a clear 'when to trust' and 'when not to rely' signal. However, it does not explicitly name alternative tools for single-venue arbitrage or other use cases, so it's not a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds value by listing the return fields, but it does not disclose behavior for invalid symbols, error responses, or any rate limiting. This is adequate given the annotations, but not richly transparent.

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, well-structured sentence that immediately states the primary action ('Fetch FMP company profile for a ticker symbol') followed by a list of included data fields. Every word contributes meaning; there is no redundancy or fluff.

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

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

For a simple one-parameter read-only tool with rich annotations and no output schema, the description adequately covers the expected return content by listing the key fields. However, it omits edge-case behavior (e.g., unknown ticker) and return format details, which slightly reduces completeness.

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

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

The schema provides only a bare 'symbol' string parameter with no description, leaving the description to carry the meaning. The description explicitly labels it a 'ticker symbol', which effectively clarifies the expected input. With a single parameter, this level of explanation compensates for zero schema coverage.

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

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

The description clearly states the tool fetches an FMP company profile for a ticker symbol and enumerates the data fields included (sector, industry, description, CEO, etc.). It is specific and unambiguous, though it does not explicitly contrast itself with the sibling tool entity_profile, which may serve a similar purpose.

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

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

The description implies usage when a user needs fundamental company profile data for a specific ticker, but it provides no explicit guidance on when to choose this tool over alternatives like entity_profile or quote. There are no exclusion criteria or mention of alternate tools, so usage guidance remains implicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description is not burdened with safety disclosure. The description adds useful context by naming FMP as the data source and enumerating the returned fields, but it does not disclose latency or rate-limit behavior, which would have added extra value.

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

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

The description is a single, front-loaded sentence that lists all key output fields without unnecessary verbiage. Every phrase adds value, making it highly concise and well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the essential return elements (price, change, ranges, volume, market cap) and names the data provider. It could have mentioned that the result is a single quote object or noted that the symbol must be valid, but overall it is sufficiently complete for its complexity level.

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

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

With 0% schema description coverage, the description must compensate for the single 'symbol' parameter. It does clarify that the parameter is a 'ticker symbol', which provides essential meaning, and the schema example 'AAPL' reinforces this. However, it does not elaborate on symbol format or potential validation rules, leaving some 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 uses a specific verb ('Fetch') and clearly identifies the resource ('current real-time quote for a ticker symbol'), listing key data fields. It distinguishes itself from siblings like quote_short by emphasizing the full real-time quote detail, making the 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?

The description clearly indicates when to use this tool (when a current real-time quote is needed) and implies it is not for historical data. However, it does not explicitly mention alternatives like historical_price or quote_short, so it falls short of full comparative 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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying the exact return fields (price, volume, percent change) and the lightweight nature of the response, which goes beyond the structured metadata.

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

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

The description is a single, well-structured sentence that is front-loaded with the core action and resource, immediately followed by scope and usage guidance. No wasted words, perfect for quick comprehension.

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 low complexity (single parameter, no output schema), the description is fully adequate. It states what the tool returns, when to use it, and its lightweight nature. Strong annotations cover safety, and the simple input schema is self-explanatory with examples.

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

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

With schema description coverage at 0%, the description carries the responsibility for parameter meaning. It clarifies 'symbol' as 'ticker symbol', which is slightly helpful, but does not provide details on formatting (e.g., case sensitivity, supported exchanges). The schema example 'TSLA' helps, but the description itself adds only marginal value beyond the parameter name.

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 ('Fetch') and resource ('FMP quote for a ticker symbol'), and clearly states the scope ('lightweight', returning only price, volume, and percent change). It effectively distinguishes itself from the sibling 'quote' and other market data tools by emphasizing the lightweight nature and the specific fields returned.

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 guidance: 'use when only the current price is needed.' This implies that for more detailed data, one should look elsewhere, but it does not explicitly name alternative tools or state when not to use it. Clear context, but missing explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds no extra behavioral context. It does not disclose what data is returned, how parameters affect results, or any operational details beyond the annotations.

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

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

The description is a three-word fragment, which is under-specification rather than conciseness. It lacks sentence structure and conveys no actionable 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?

With no output schema and a generic description, the tool is severely underspecified. The agent has no way to know what ratios are returned, how the period/limit parameters work, or how to interpret the output.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does not: 'Financial ratios' provides no meaning for 'symbol', 'limit', or 'period', leaving their roles entirely unexplained.

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 'Financial ratios' is a noun phrase that merely restates the tool name with a qualifier, lacking a specific verb or resource. It does not indicate that this returns ratios for a symbol or how it differs from sibling tools like key_metrics or financial_growth.

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. The description does not mention the required symbol parameter, typical use cases, or any exclusions, leaving the agent to guess.

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?

While annotations already declare readOnlyHint=true and idempotentHint=true, the description adds meaningful behavioral context: it is scoped to the user's identifier (anonymous IP, BYO key hash, or account ID), and it explains the relationship with remember/forget. This goes beyond the annotations.

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

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

Three sentences with no fluff. The primary action is stated first, followed by usage guidance and scope. Every sentence earns its place, 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 tool with one optional parameter, the description is complete: it explains the main operation, the list behavior, use cases, scope, and relationship to sibling tools. No output schema is needed, and the description covers enough for effective use.

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

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

The schema covers the key parameter fully, but the description enriches it by giving examples of what keys typically store (user's target ticker, address, research notes) and clarifies that omitting the key lists all saved keys. This adds meaning beyond the schema's dry 'omit to list all keys'.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This provides a specific verb and resource, and distinguishes it from sibling tools like remember and forget by focusing on retrieval.

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

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

The description explicitly tells when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions pairing with remember and forget, giving clear usage context and related 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 contradicts the annotation `readOnlyHint: true`. The description states that setting `mark_read:true` will flag events as read, causing the next call to show only newer events — a state-changing side effect. This directly contradicts the read-only hint, constituting an annotation contradiction.

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

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

The description is well-structured, starting with the core action in the first sentence, then providing return details, filtering options, a side-effect note, and an alternative access method. Every sentence adds useful information without redundancy, and it is appropriately sized.

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 (5 optional parameters, no output schema), the description covers purpose, return payload composition, filtering, side effects of mark_read, and an alternative endpoint. It also mentions polling suitability, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete example for `type` ('sec_8k'), confirming `since` expects an ISO timestamp, and explaining the side effect of `mark_read` in plain language, which is helpful beyond the schema descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('Pull fired events from your subscription feed') and resource ('subscription feed'). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts with filtering options.

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

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

The description provides clear context for when to use the tool, mentioning polling suitability and an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly name excluded use cases or directly contrast with sibling tools, so it stops short of a perfect score.

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 richly discloses behavior beyond annotations: it fans out to SEC EDGAR, uses GDELT with GNews fallback on rate-limit/5xx, notes the USPTO PatentsView API sunset and soft-fail, and describes the return structure (changes[] grouped by source, total_changes, and pipeworx:// URIs). Annotations already mark it read-only/non-destructive, and the description adds significant context 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 front-loaded with concrete user-phrase examples, then efficiently explains source routing, parameters, return shape, and the alternative tool. Each sentence carries unique information—there is no filler or redundancy—making the length 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 multi-source fan-out, fallback logic, recent-window semantics, and no output schema, the description is remarkably complete. It covers return structure, `since` syntax, source behaviors, and a clear alternative for static-profile needs, so an agent can confidently select and invoke it without additional documentation.

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

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

The input schema already covers all three parameters with clear descriptions (type enum, since formats, value examples), so the baseline is 3. The description adds only modest value by restating ISO/relative formats and suggesting "30d" or "1m" for typical monitoring, but it does not introduce meaning substantially beyond the schema.

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

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

The description clearly identifies the tool as a change feed for a company over a recent window, anchored by multiple concrete natural-language examples ("What's new with X", "latest on Y"). It also names the specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from entity_profile, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance via query patterns ("what happened to Z this week/month/quarter") and provides a direct alternative: "Use entity_profile instead when you want the static profile...". It also clarifies fallback behavior and a recommended default (`since` of "30d" or "1m"), which helps an agent decide when to invoke this tool.

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

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

The annotations already mark the operation as idempotent and non-destructive; the description adds crucial behavioral details: memory is scoped by an identifier, authenticated users get persistent storage, and anonymous sessions expire after 24 hours. This goes beyond the structured annotations and disambiguates how the data behaves.

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 action verb, uses bullet-like examples inline without being verbose. Every sentence adds meaningful information, from use case to persistence to the companion tools.

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 two-parameter write tool with no output schema, the description covers purpose, usage, persistence, and relationship to siblings. It is complete enough for an agent to select and 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 documents both parameters (key and value) with examples. The description adds the overarching 'key-value pair' abstraction and the scoping detail, but doesn't elaborate further. Given 100% schema coverage, the description's contribution is moderate, hence a 4.

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

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

The description opens with a clear action ('Save data the agent will need to reuse later') and specifies the resource (key-value data). It distinguishes from sibling tools by explicitly mentioning pairing with recall and forget, placing it within a memory workflow.

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

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

It provides explicit use cases ('a resolved ticker, a target address, a user preference') and the benefit ('so you don't have to look it up again'). It also clarifies persistence scoping and duration, which helps decide when to use it. While it doesn't formally list 'when not to use,' 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 a read-only, idempotent, open-world, non-destructive operation. The description adds beyond this: it discloses that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and that LEI/FIGI enrichment degrades gracefully if upstream sources fail. It also reveals internal cascading across endpoints, which is valuable behavioral context.

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

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

Though paragraph-length, the description is tightly structured: user intent examples → core purpose → use directive → per-type details → fallback behavior → efficiency note. Every clause carries information, and the flow is logical. No filler or repetition. It earns its length given the tool's complexity.

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

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

The tool has no output schema, so the description must cover return behavior. It does: for drug, it names the returned fields ('RxCUI + ingredient + brand'); for company, it enumerates the identifier set (CIK, ticker, LEI, FIGI) and its sources. It also covers failure modes (unresolved identifiers, upstream unavailability). Given two params and rich annotations, this is fully complete.

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

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

Schema coverage is 100%, but the description significantly augments the parameter docs. It explains the 'type' enum with details on what each type returns (company: CIK, ticker, LEI, ownership, FIGI; drug: RxCUI, ingredient, brand). For 'value', it provides exact formats and examples (ticker 'AAPL', CIK '0000320193', drug names). This goes well beyond the schema's terse 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 concrete example queries, then states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This is a specific verb + resource + outcome. It also distinguishes from siblings by positioning itself as the 'FIRST' step when an ID is needed, with a clear contrast to search/quote tools.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' This is a direct usage directive. It also lists supported entity types and what can be passed as input, indicating when it applies. The 'replaces 2-3 manual lookups' line further signals its role as a consolidated entry point.

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

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

Annotations (readOnly, openWorld, idempotent, non-destructive) already cover safety. The description adds meaningful process details beyond those: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This explains the operational flow 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?

Three concise sentences: action, process, use case. Every sentence carries unique value, no fluff or repetition. The most important information (compare, rank, returns) is front-loaded.

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

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

The description fully explains the tool's purpose, methodology, use case, and return format (ranked list with score, confidence, signal density). Combined with a comprehensive input schema and safety annotations, the agent has all necessary context to invoke the tool correctly without needing an output schema.

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

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

The input schema already provides 100% coverage, including the crucial note that the first entity is treated as the 'subject' and rest are competitors. The description adds only a high-level 'your brand + N competitors' but does not improve on the schema's parameter-level detail. Since the schema fully documents all four parameters, the baseline of 3 is appropriate.

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

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

The description clearly states the specific action: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI presence and ranking. The inclusion of 'Probes each entity with ai_visibility_check' and 'ranks by score' makes 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?

The description explicitly gives a use case: 'Useful for competitive AI-marketing audits.' It also implies when to use (when you need a multi-entity comparison) and effectively contrasts with ai_visibility_check by showing this is the multi-entity variant. However, it does not explicitly name alternatives or say when NOT to use, 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?

Beyond the annotations (read-only, open-world, idempotent), the description adds crucial behavioral details: partial failure handling, first-measurement latency of 5-30s, and that 'sources_failed' will be listed on timeout. It also discloses the ecosystem scope limitation, going well beyond what annotations provide.

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

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

The description is front-loaded with the purpose, followed by usage, return structure, scope, and failure behavior. Each sentence carries substantive information without repetition or filler, appropriate for a composite 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?

Without an output schema, the description lists the exact summary fields returned (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) plus additional detail types. It covers ecosystem scope and failure modes, making it complete for an agent to decide and invoke.

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

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

Schema coverage is 100%: both 'package' and 'version' have descriptions covering scoped packages and default-to-latest behavior. The tool description does not add parameter-specific semantics beyond what the schema already states, so a 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 is a composite check for adding an npm package, combining deps.dev and bundlephobia data. It is specific about the verb ('check'), the resource ('npm package'), and the scope of the check, distinguishing it from any sibling tools.

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

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

Provides explicit when-to-use guidance with query examples ('is X safe / popular / small') and an explicit exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent both when and when not to use the tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds no additional behavioral context. There is no mention of matching behavior, result limits, or how the exchange parameter affects results, so the description provides no value beyond the annotations.

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

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

The description is a single phrase, technically concise, but it is under-specified for a tool with three parameters. This is not efficient brevity; it omits necessary information, making it closer to a tautology than a useful 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?

Given the tool has three parameters, no output schema, and minimal description, the description is incomplete. It fails to explain the purpose of limit/exchange or the expected output, leaving significant gaps for an agent to operate 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?

With 0% schema description coverage, the description must compensate, but it only vaguely implies 'query' is a company name. The 'limit' and 'exchange' parameters are not explained at all, leaving their semantics unclear.

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 'Company-name search' clearly states the tool searches by company name, distinguishing it from search_symbol (likely ticker-based) and search_within. The verb 'search' and resource 'company name' are specific, though terse.

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 search_symbol or search_within. The description does not mention exclusions or contexts where this tool is preferred, leaving the agent to infer usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no extra behavioral context, such as whether the search is exact-match or fuzzy, whether results are limited, or any pagination/ordering behavior. With zero extra value, a 2 is appropriate.

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 succinct but under-specified. It is not a properly sized description because it omits essential information that the agent needs. Being short for the sake of brevity is not valuable here; the single sentence does not earn its place.

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

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

With 3 parameters (one required), no output schema, and a description that only says 'Symbol search.', the tool is severely underdocumented. The agent has no idea what inputs mean, what to expect as output, or how to interpret results. Given the richness of sibling financial tools, this description is wholly inadequate.

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

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

Schema description coverage is 0%, and the description does not explain any parameters. The schema lists 'query', 'limit', and 'exchange' with no descriptions, and the overall description 'Symbol search.' provides no semantic meaning for these fields. This is a critical gap.

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 'Symbol search.' is essentially a tautology of the tool name 'Search Symbol'. It does not specify what symbols are searched (e.g., stock tickers, crypto), what the search returns, or how it differs from sibling tools like search_name or quote.

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

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

The description provides no guidance on when to use this tool versus alternatives. With siblings like search_name, search_within, entity_profile, and quote, there is no indication of which scenarios call for search_symbol.

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

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

The description adds rich behavioral context beyond annotations: it discloses the embedding model (BGE-base-en), cosine similarity over 500-char windows, the 200K char cap with truncation flagging, and return details like character offsets and similarity scores. This is far more than the read-only/idempotent annotations provide.

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

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

Each of the five sentences provides distinct value—purpose, parameter usage, when-to-use, sibling pairing, and technical constraints. It is front-loaded and avoids redundancy with the schema, making every sentence earn its place.

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

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

Despite lacking an output schema, the description specifies the return format (top-N passages, offsets, similarity scores), the truncation behavior, and the intended workflow with a sibling tool. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description enriches parameter meaning by explaining that 'text' is the already-pulled record, 'query' is natural language with examples, and 'limit' corresponds to top-N passages. It adds workflow context that the schema's descriptions do not fully convey.

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, with a specific verb ('search') and resource ('a fetched record'). It distinguishes itself from siblings by referencing ask_pipeworx_grounded and explaining its niche, using concrete examples like SEC 10-K bodies.

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 use when the record is too big to fit in the prompt, and describes a complementary workflow with ask_pipeworx_grounded, giving the agent clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the 'paid' constraint, which is useful access context beyond annotations, but it does not disclose return format, pagination behavior, or rate limits.

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

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

The description is extremely short, but this is under-specification rather than effective conciseness. Two words do not provide enough information to be useful, similar to the 'Process' example.

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 three undocumented parameters, the description must explain return values and parameter usage, but it does neither. The tool is not adequately specified 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?

Schema description coverage is 0% and the description does not compensate at all. It mentions no meaning for symbols, page, or limit; the agent must guess that symbols are ticker symbols and page/limit control pagination.

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 'News (paid).' restates the title's 'News' and adds only the payment caveat; it lacks any verb or explicit object, so it doesn't actually say what the tool does (e.g., retrieve or list stock news). It is more of a fragment than a purpose statement.

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?

There is no guidance on when to use this tool, what problem it solves, or how it differs from sibling tools like quote, recent_alerts, or earnings_calendar. The description provides no context for selection.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds only the word 'paid', which is a cost/access note, but lacks details on rate limits, output structure, or any nuances beyond the schema. With annotations present, this small addition warrants a mid-range score, but no contradiction exists.

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

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

Three words cannot adequately describe a tool with 17 parameters and rich filtering options. While there is no redundancy, the text is under-specified; it sacrifices necessary detail for brevity.

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

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

For a complex screener with 17 parameters, a one-phrase description is completely inadequate. It does not explain what results look like, how filters work, or any prerequisites. The schema and annotations cover the data model, but the description itself fails to provide holistic 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?

All 17 parameters have descriptions in the schema, giving 100% coverage. The tool description itself mentions none of the parameters, but the schema fully documents them, so a 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 'Stock screener (paid)' essentially restates the tool's title with a parenthetical cost note. It lacks a verb and does not explain what the tool does (e.g., 'filters stocks by criteria'). This is a tautology rather than a functional description.

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 any sibling tools like 'quote', 'search_symbol', or 'intraday'. The description only mentions that it is paid, which is a cost constraint, not a usage recommendation.

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 annotations: OAuth account requirement, anonymous/BYO inability to persist, SMS 10/day cap, phone verification at /account, webhook signing secret returned once, and auto-disable on repeated failures. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose and return value. It packs many relevant details into a single paragraph, though it omits webhook and two supported types (patent_grant, clinical_trial) from the narrative, creating minor redundancy with the schema.

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

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

For a complex tool with no output schema, the description covers many aspects (auth, types, delivery, limits) but omits webhook from the delivery channels list and fails to mention patent_grant and clinical_trial types despite them being in the schema enum. The schema fills these gaps, but the description alone is incomplete.

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 goes beyond the schema by adding concrete examples like sec_8k items:["5.02"] = officer change, polymarket_edge topic:"fed", and delivery constraints like phone verification and rate caps.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb and resource, and the scope is distinct from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides actionable context: requires a Pipeworx OAuth account, explains supported subscription types, and describes delivery channels plus how to pull from the feed via recent_alerts. It does not explicitly name alternatives for when not to use it, but the guidance is clear enough.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds valuable behavioral context: it draws from the live catalog, returns exact tool and argument shapes, and supports topic-based focusing. No contradictions with annotations.

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

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

The description is long but well-structured, front-loaded with sample user phrases and organized with a clear flow: intent → return value → invocation options → when to use. No wasted filler, though it could be tightened slightly without losing value.

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

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

With no output schema, the description fully covers the return format (category-bucketed examples with tool+argument shapes), invocation variants (no args vs topic), and usage context. It also mentions how to learn meta-tool usage, making it self-sufficient for onboarding.

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

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

Schema coverage is 100% with a detailed description of the optional topic parameter, including enum-like values and omit-for-spread behavior. The description adds examples ('finance', 'pharma', 'betting') and the word 'focus', but these are essentially redundant with the schema, 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 explicitly identifies this as the onboarding entry point for a newly connected agent, listing the exact user intents it serves (e.g., 'what can I ask Pipeworx?'). It clearly differentiates from siblings like discover_tools or ask_pipeworx by stating it returns category-bucketed example questions with exact tool+argument shapes.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments vs. a topic. However, it does not explicitly mention when not to use it or name alternatives for exclusion, though referencing meta-tools implies their use for other purposes.

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=false, destructiveHint=false, and idempotentHint=true. The description adds the key behavior that the row is 'deactivated (not deleted)' and explains ownership enforcement, which aligns with annotations and provides extra context about the non-destructive nature and scope of the operation. 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 with three short sentences: the action, the ownership constraint, and the behavioral outcome. Each sentence is purposeful and front-loaded, with no redundant or filler content. It earns its place efficiently.

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

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

This is a simple tool with one parameter, full annotations, and no output schema. The description fully covers what the tool does, the key constraint (ownership), and the effect (deactivation with historical events preserved). There is no missing information that an agent would need to select and invoke the tool correctly.

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

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

The input schema provides a description for the single 'id' parameter: 'Subscription id (uuid) returned by subscribe' — this is 100% schema coverage. The tool description only says 'by id', which adds no new meaning beyond the schema. Given the high schema coverage, a baseline of 3 is appropriate; the description does not compensate further.

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 and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation. The title 'Unsubscribe from Alerts' further reinforces the action, leaving no ambiguity.

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

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

The description provides important context: ownership is enforced (only your own subscriptions), and the subscription is deactivated rather than deleted, with historical events retained in recent_alerts. This implies when to use the tool (to cancel) and the alternative for viewing historical data, though it does not explicitly 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 annotations (readOnly, idempotent, non-destructive), the description details return verdicts, the meaning of 'could_not_verify' (with verification_error and that it must not be shown as evidence), and the unsupported state. This enriches the caller's understanding of edge cases, which 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 about 200 words but every sentence adds value: trigger phrases, routing logic, return value, and error semantics are all packed in without redundancy. The content is front-loaded with the core purpose and usage, making it easy to scan 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?

For a complex tool with no output schema, the description is exceptionally complete: it enumerates the six possible verdicts, explains the structured vs. grounded pipeline, states that the answer includes a pipeworx:// citation and reasoning, and addresses both error and unsupported cases. No critical operational detail 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?

Even though schema coverage is 100%, the description adds significant meaning: it explains that tolerance_pct overrides the tolerance implied by the claim wording, shows the allowed range (0.5–50), and suggests setting 1–2 for hallucination detection. The claim parameter is also illustrated with concrete examples, going beyond the schema's simple type/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 names a specific verb ('validate' / 'verify') and resource ('natural-language claim verification against authoritative sources'), and immediately distinguishes its scope by giving trigger phrases. It also separates two execution paths (SEC EDGAR for company-financial claims vs. a grounded pipeline for everything else), making it clearly distinct from sibling tools like ask_pipeworx_grounded or compare_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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' and gives concrete examples of when to use it over alternatives (e.g., company-financial claims vs. other claims). It also explains that it replaces multiple sequential calls, reinforcing when to prefer this single tool over composing several others.

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