Outlook Calendar

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: default model (Workers AI Llama-3.3-70b, free), that Anthropic probing requires a BYO key, and the user bears direct cost. It also details the return structure (per-model {score, confidence, signals, raw_response} + combined view), going beyond what annotations provide 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 a single, well-structured paragraph of about 4 sentences. It front-loads the primary action and result (probing and scoring), then explains the default model and optional key, then describes the return, and finally lists use cases. Every sentence adds value; there is no redundancy or fluff. It is optimally sized for an AI agent to quickly grasp the tool's role.

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 4 parameters (1 required), 100% schema coverage, and no output schema, the description provides comprehensive context. It explains all parameters, the default behavior, the return structure, and example use cases. The tool's complexity (multiple models, optional key, scoring) is fully covered. An AI agent can confidently select and invoke this tool based on the description alone.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema. It explains that `entity` is the thing to ask about, `models` can be omitted for default, `_apiKey` is only needed for Anthropic, and `context` disambiguates common names. It also clarifies that the key is passed through to api.anthropic.com, addressing privacy/security concerns. This exceeds the bare schema 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 clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the action (probe, score), the resource (LLMs), and the domain (visibility checks). The title 'AI Visibility Check' reinforces this. Among sibling tools like 'ask_pipeworx' and 'deep_research', this tool is uniquely positioned for cross-model visibility scoring, making it well-distinguished.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to provide parameters like `_apiKey` and `models`. However, it does not explicitly state when NOT to use this tool or mention alternatives among siblings. The directive is clear for appropriate scenarios, but lacks exclusion 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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds useful behavioral context: it routes across many sources, fills arguments automatically, returns structured answers with stable citation URIs, and handles live news routes. It doesn't disclose latency, failure modes, or limits, but for a read-only QA tool the disclosure is adequate.

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 overly long and contains an embedded meta-instruction block ('Step only when needed...') that reads like agent orchestration notes rather than clean tool documentation. It repeats categories, mixes all-caps directives with examples, and is not tightly structured despite good front-loading. Several sentences could be consolidated.

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-required-parameter read-only tool, the description is functionally complete: it covers domains, routing behavior, output format (citations), example queries, and when to use alternatives. Minor gaps like rate limits or unsupported query types are not essential given the annotations and simple input schema. The clutter slightly reduces usability but not 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 input schema already fully documents the single question parameter and all aliases with 100% coverage. The description adds practical semantic grounding by listing example queries and the kinds of phrasings the tool accepts ('what is', 'look up', 'find', 'get the latest'). This goes beyond the schema's bare type/alias info.

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 a routing/QA tool: it takes a natural-language question, routes it to one of 5,710 tools across verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It enumerates many supported domains and gives concrete examples, making it easy to distinguish from broader or more specialized siblings.

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

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

Usage guidance is explicit and actionable: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' plus a list of trigger phrasings. It also names alternatives: ask_pipeworx_grounded for hallucination-resistant verbatim answers, deep_research for broad/multi-part queries, and notes news routing behavior. This is strong when-to-use and 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description benefits from a lower burden. It still adds meaningful behavioral context: candidate routing improvements are enabled live, no candidate is currently active, and it currently matches ask_pipeworx exactly. The 'falls back to nothing' warning is particularly useful and goes beyond what annotations express.

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 minimal but every sentence earns its place: it establishes identity, explains the experimental status, reports current state, gives usage instruction, and clarifies fallback behavior. It front-loads the core 'beta version' framing before diving into operational details. Slight redundancy around matching ask_pipeworx is minor.

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 is a router with no output schema, the description provides essential context: same response shape as ask_pipeworx, same arguments, and experimental routing behavior. It tells the agent that this is a full working router and not a stub. The only gap is that an agent unfamiliar with ask_pipeworx would still need to look at that sibling for more detail, but the pointer is explicit.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including aliases. The description adds that arguments are identical to ask_pipeworx but does not elaborate on parameter meaning or usage beyond that. This is the appropriate baseline for tool definitions where the schema carries the parameter documentation 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 clearly names the tool as a beta version of ask_pipeworx and explains that it is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by its purpose as the experimental routing edge. This gives an agent a precise understanding of what the tool is and how it relates to its sibling.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router to decide merges. It also clarifies that it does not fall back to anything and is a full working router, preventing hesitation about reliability. This is strong when-to-use guidance with differentiation from the main 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?

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds genuinely useful disclosure: the exact success return shape, an explicit refusal contract with five named refusal reasons, grounding in tool-result content only, and an extra LLM call cost. Nothing contradicts 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?

Dense but every sentence earns its place: purpose, behavior, return/refusal contract, use cases, and cost comparison are all packed efficiently. Key information is front-loaded, with the money line ('hallucination-resistant answer mode for high-stakes reads') first.

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 provides a full answer/refusal contract, concrete high-stakes usage domains, and a cost-based comparison with the sibling tool. An agent has enough to select and invoke it correctly, and to interpret non-answer results via refusal_reason.

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 schema already documents the question parameter and aliases. The description adds only high-level context (same routing as ask_pipeworx, picks the right tool and fills arguments) without adding per-parameter semantics, which is acceptable given full 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 uses a specific verb and resource ('hallucination-resistant answer mode', 'extracts the answer using ONLY what the tool result contains') and explicitly contrasts itself with ask_pipeworx, making sibling differentiation clear. The title 'Grounded' is reinforced with concrete behavioral detail rather than mere restatement.

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 (high-stakes reads, answers that will be quoted/cited/acted on, must-not-invent-facts domains: financial, legal, medical, public statements) and an explicit when-not-to-use directive ('prefer ask_pipeworx for casual lookups'). It names the alternative directly.

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 adds substantial behavioral detail: low-confidence short-circuit with status, closed/dead market handling, wide-spread tradeability flag, resolution-rule risk parsing, and response structure. 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?

Front-loaded with main purpose and usage. Structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) for skimmability. While verbose, each section adds necessary detail and earns its place.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, edge cases), the description is remarkably thorough. It covers safety, error states, response shapes, resolution rules, and even internal fallback mechanisms. No output schema, but the description provides complete mapping of return fields.

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

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

Schema covers all 3 parameters with 100% coverage. Description adds further value by explaining market input formats, default depth ('thorough'), and include_raw's purpose and size impact. This enriches understanding beyond the schema.

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

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

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data. Specific verb-resource: 'Research a Polymarket bet'. Input types (slug, URL, question text) and output (evidence packet + comparison) are explicit. Distinguishes from siblings like polymarket_arbitrage and polymarket_edges by its research scope.

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

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

Provides clear use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Does not explicitly state when not to use or name alternatives, but the context and sibling list make it inferable.

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 safe, read-only, idempotent behavior. The description adds important traits: correct handling of off-calendar fiscal years for companies, sorting by primary metric, and the data sources (SEC EDGAR/XBRL, FAERS, FDA, clinicaltrials.gov). 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 relatively long but every sentence earns its place by providing essential examples, behavioral details, and data-source specifics. It front-loads example queries to quickly orient the agent. Slight wordiness could be trimmed, but overall it is efficient for the complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the lack of an output schema, the description covers all necessary aspects. It explains edge cases (off-calendar fiscal years), result ordering, and return format. No gaps remain for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter descriptions. It explains the difference between company and drug types (what data is pulled for each), the constraints on values (2–5 items, tickers vs drug names), and the behavior of sorting by primary metric. It also mentions the returns format (paired data + citation URIs).

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

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

The description starts with concrete example queries, identifies the verb 'compare' and resource 'entities', and clearly states it performs side-by-side comparisons of 2–5 companies or drugs. It differentiates from sibling tools like entity_profile by explaining that it replaces sequential single-entity 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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also implicitly covers when not to use (e.g., for single entity profiles, use entity_profile instead).

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail: parallel facet routing, gaps[] with no invented answers, contradictions[], hop fields, citation fetchability, semantic excerpting, and latency expectations. This goes far beyond the annotations and does not contradict them.

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

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

The description is long but every clause earns its place: account requirement, purpose, usage boundaries, depth semantics, return content, citation behavior, extraction behavior, and latency. It is front-loaded with the most critical operational constraint and contains no 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?

With no output schema, the description carries the full burden of explaining return value semantics, and it does so: findings packet fields, gaps[], contradictions[], hop, citation_uri, and fetchability. It also covers auth, pricing, latency, and when to prefer a sibling tool, making the tool fully usable from the description alone.

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

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

Schema coverage is 100%, and the description adds real value on top: it explains quick=3 single-hop, standard=3 default with gap-recovery and contradictions, and thorough=6 paid with iterative follow-up. This gives the agent actionable semantics that the enum alone does not 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 states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly distinguishes itself from open-web search and directs single-lookup questions to ask_pipeworx, making sibling differentiation 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 explicitly says when to use this tool (broad/multi-part structured-data questions) and when not to (single lookups -> ask_pipeworx). It also covers the account prerequisite and the alternative for unsigned-in users, so an agent can route correctly.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: returns top-N most relevant tools with full schemas and examples, ready to call directly. No contradictions.

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

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

Description is relatively long but well-structured: purpose, domain list, return format, usage guidance. Every sentence adds value, though slight redundancy in listing aliases twice could be trimmed.

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

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

Given no output schema, the description adequately explains return format (top-N tools with descriptions and schemas). Parameter list is fully covered. Missing details on pagination or error handling, but acceptable for a discovery tool.

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

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

Schema coverage is 100% with descriptions. The description adds that parameters like q, task, search, description are aliases for query, which enhances understanding beyond the schema.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes itself from sibling tools (specific tools like deep_research) by being a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. Could be improved by explicitly stating when not to use, but still strong.

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

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

Description adds extensive behavioral context beyond annotations: describes parallel fan-out across multiple APIs, specific data elements returned, patent sunset date, and fallback mechanisms. No contradictions with annotations (readOnly, idempotent, etc.).

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

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

Description is detailed but well-structured, front-loading example queries and usage guidance. Every sentence adds value; however, it could be slightly more concise without losing critical context.

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

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

Given no output schema, the description comprehensively covers return values, data sources, limitations (patent sunset), and error handling (soft-fail). Provides enough detail for an agent to understand what to expect.

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

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

Schema covers 100% of parameters with descriptions. Description adds meaningful context: examples ('AAPL', '0000320193'), clarifies that names are not supported, and explains the zero-padded CIK format. Enhances 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 clearly states the tool returns a full cross-source profile of US public companies, listing multiple data sources and specific return fields. It distinguishes itself from sibling tools like resolve_entity by specifying that names are not supported here.

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

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

Explicitly tells when to use ('ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view') and when not ('names not supported — use resolve_entity first'). Provides clear context for 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds useful context by describing it as a 'lightweight free/busy view' and enumerating returned fields, but it does not go further into authentication needs, rate limits, or edge-case behavior like empty calendars or timezone handling.

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 focused sentences. The first sentence front-loads the core behavior and output fields, and the second adds practical use-case guidance. There is no filler or repetition of 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?

The tool is simple: one optional, well-documented parameter, a clear read-only operation, and a description that lists the main output fields (start, end, subject, all-day flag). Minor details like ordering or timezone are not specified, but they are unlikely to prevent 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?

Schema coverage is 100% and the only parameter, days_ahead, is already documented with its type and default value (7). The description's 'next N days' phrasing aligns with the schema but does not add new semantics beyond it, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Return') and a specific resource ('user's busy time windows from their Outlook / Microsoft 365 calendar over the next N days'). It also frames the tool as a 'lightweight free/busy view,' which distinguishes it from sibling tools like list_events or get_event that would return broader calendar event 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?

The description explicitly says 'Use to find when the user is available or to identify scheduling conflicts before proposing a meeting time,' which gives a clear contextual trigger. It does not name alternatives or state when not to use it, so it stops short of a full 5.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description only says 'Delete', which matches but adds no further behavioral context (e.g., irreversibility, no side effects). 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?

Two sentences, zero wasted words. Information is front-loaded and concise.

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

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

For a simple one-parameter tool with no output schema and good annotations, the description covers purpose and usage adequately. Could mention error behavior on missing key, but not essential.

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 describes the key parameter as 'Memory key to delete'. Tool description does not add additional semantic meaning beyond the schema, so baseline of 3 applies.

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

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

Clearly states 'Delete a previously stored memory by key'. Verb+resource is specific, and distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or to clear sensitive data. Also mentions pairing with remember and recall, which provides context about 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/key links, and emits markdown format. 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?

Three sentences, front-loaded with action and purpose, no waste. Each sentence adds value.

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

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

Tool is simple with clear output (text blob). Description explains output format and placement. No output schema needed.

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

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

Schema description coverage is 100%, so baseline 3. Description reiterates max_links usage but does not add significant new meaning beyond schema.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb ('Generate') and resource ('llms.txt file for any URL'). Differentiates from sibling tools which are mostly research and bet-related.

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?

Lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. Does not explicitly state when not to use or provide alternatives, but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds value by listing the returned fields, which is useful since no output schema exists, but adds no caveats about errors, permissions, 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?

Two concise sentences, zero filler. The core action is front-loaded, followed by the return payload list and a direct usage cue.

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 single-parameter read-only tool with full schema coverage and rich annotations, the description provides all necessary calling context. The absence of an output schema is compensated by the explicit enumeration of returned fields.

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

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

Schema coverage is 100%, and the id parameter is already described as 'The Microsoft Graph event ID to retrieve.' The description echoes the role of the parameter ('by its ID') but adds no deeper semantic detail beyond what the schema provides.

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

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

States a specific verb and resource: 'Get full details of a single Outlook / Microsoft 365 calendar event by its ID.' It clearly differentiates from list_events by targeting a single event and enumerating the returned fields.

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 after list_events to inspect a specific meeting,' providing clear context and a sequencing cue. It does not mention exclusions or alternative tools, but for a simple lookup tool this 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context by revealing that it returns the signed-in user's display name, mail, and UPN. No contradictions or hidden behavioral surprises are apparent.

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

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

Two compact sentences with no filler. The first sentence front-loads the action, scope, and output fields; the second gives a practical use case. Every word earns its place.

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

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

For a parameterless, read-only profile fetch with rich annotations, the description covers the core need: what the tool returns and why to call it. It does not describe error behavior or exact value formats, but these are minor given the tool's simplicity and lack of parameters.

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

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

The tool has zero parameters and 100% schema description coverage, so no parameter documentation is needed. Credit is given per the baseline for parameterless tools; the description focuses on output fields, which is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('signed-in user's Microsoft 365 / Outlook profile') and enumerates the exact fields returned. It clearly differentiates this from entity/profile-related siblings by emphasizing the signed-in user's own identity.

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

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

It explicitly states when to use the tool: 'Use to confirm whose calendar is connected.' This gives clear context, though it does not name alternatives or exclusions. Still, the use case is actionable and sufficient for a zero-parameter 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, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context by specifying the scope ('accessible') and the exact returned fields (ID, name, owner, edit permission, default calendar).

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 with no filler. The action and scope are front-loaded, followed by return-value detail and a clear usage statement. Every sentence earns its place.

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

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

For a zero-parameter read-only listing tool, the description adequately covers purpose, scope, and return fields. No output schema exists, so the enumerated fields help compensate, though pagination or count behavior is not mentioned—minor given openWorldHint.

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 tool takes zero parameters, so the baseline is 4. The description adds value by explaining what the response will contain, which compensates for the absence of an output 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?

States a specific verb ('List') and resource ('calendars accessible in the user's Outlook / Microsoft 365 account'), and enumerates what is returned. Clearly distinguishes itself from sibling tools like list_events and list_subscriptions.

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 use it 'to discover which calendars exist,' giving clear invocation context. It does not mention when not to use it or name alternatives, but the usage context is sufficient given the sibling set.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds useful behavioral context: the default 7-day window and the specific event fields that will be returned.

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

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

Three short sentences front-load the core action, then provide the return contract and usage guidance. No filler or repetition that weakens the definition.

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

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

For a read-only list operation with fully documented optional parameters and annotations covering safety, the description covers defaults, output fields, and intended use. Nothing essential is missing for an agent to call 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 100%, so the start, end, and top parameters are already fully documented with defaults and formats. The description adds the default 7-day window and return fields but does not add meaning beyond the schema for the parameters themselves.

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

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

States a specific verb and resource: list events from the user's Outlook/Microsoft 365 calendar. The time-window scope and return fields make it clearly distinct from siblings such as get_event, list_calendars, and find_meeting_times without needing to open the schema.

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

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

Explicitly says to use it to see scheduled meetings or appointments, giving a clear selection context. It does not explicitly name alternatives or exclusions, but the context is enough for an agent to choose it over sibling event tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying return fields and optional parameter for inactive subscriptions, consistent with annotations.

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

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

Two concise sentences: first lists purpose and return fields, second provides usage guidance. No wasted words, front-loaded effectively.

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?

Complete for a list tool with single optional parameter. Absence of output schema compensated by listing fields. Usage context and siblings are clear.

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 parameter description is already present. Description does not add extra meaning beyond the schema's description for 'include_inactive'. Baseline score 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Distinguishes from siblings like subscribe/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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use and implies 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 only set all hints to false, so the description carries full burden. It discloses the claim_token return-and-query mechanism, daily rate limit of 5, free usage (no tool-call quota), and that the team reads digests daily. This is rich, non-obvious behavioral context well beyond annotations.

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

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

Although long, every sentence is information-dense and earns its place. Purpose is front-loaded, followed by usage rules, exclusions, claim_token behavior, and rate limits. No filler or repetition of schema 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?

Given no output schema, the description appropriately explains the key return behavior (claim_token and later status reads). It also covers usage limits, exclusions, and quality guidelines. Combined with the detailed input schema, this is fully adequate for an agent to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so parameters already have meaning. The description adds extra value by explaining claim_token usage with a concrete example ('pipeworx_feedback({claim_token:"pwfb_…"})') and specifying message content constraints (don't paste end-user prompt, be specific, 1-2 sentences). This exceeds schema baseline without duplicating it.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This distinguishes the tool from all siblings, which are research or subscription tools, and aligns with the title.

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

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

Explicit 'Use when' conditions cover bug, feature/data_gap, and praise categories. It also states when NOT to use (feedback about other MCP servers should go to that server instead) and gives guidance on describing issues in terms of Pipeworx tools/packs. This is model guidance for appropriate 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. The description adds significant behavioral context: self-aggregating from CF analytics-engine, no PII, cache duration 5min-1h, and derivation from call patterns. No contradictions, and all these add value beyond annotations.

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

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

The description is front-loaded with a clear summary, then use-case bullets. Every sentence contributes meaning, though the bullet point list is slightly verbose. Overall 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?

Given the tool's simplicity (one optional param, no output schema), the description covers all essential aspects: return type, data source, privacy, caching, and window semantics. Nothing essential is missing.

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

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

Schema description coverage is 100% (one parameter with enum and description). The description enriches the schema by explaining the trade-off between short and long windows ('highlight what's hot right now' vs 'show steady-state demand'), providing semantic value beyond the schema.

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

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

The description uses a specific verb ('Returns') and resource ('top tools, top packs, and total call volume') with a unique framing ('What other AI agents are calling on Pipeworx right now'). This clearly distinguishes it from siblings like discover_tools or ask_pipeworx, fulfilling the highest clarity standard.

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?

Three explicit use cases are provided (discovering hot data, confirming canonical tool, aligning use case). While it doesn't state when not to use or name alternatives, the context is sufficiently clear 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 description discloses extensive behavioral details: internal checks (monotonicity, partition sum, Jaccard similarity filter, placeholder filter), fill check against live CLOB depth, and response structure. Annotations already indicate read-only, idempotent, non-destructive, and the description adds rich context without contradiction.

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

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

The description is well-structured with clear paragraphs and front-loaded main purpose. It is fairly verbose but every sentence adds value. Could be slightly more concise, but the structure is logical and effective.

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

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

Despite no output schema, the description details the response fields (opportunities[], partition_check in event mode, fill check). It covers all modes, internal algorithms, and edge cases (placeholder filter, similarity anchor). The tool is complex and the description is remarkably complete.

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

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

Schema description coverage is 100% for both parameters, but the description adds significant meaning: explains the no-args case (not in schema), how event slug vs topic work, the Jaccard similarity anchor, partition filter, and fill check. It goes far beyond the schema definitions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no-args trending scan, event mode for a specific market, and topic mode for cross-event scanning. This is very specific and distinguishes from sibling tools.

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

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

The description explicitly tells when to use each argument: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market): ...', 'topic (for cross-event scanning): ...'. It also provides guidance on when not to trade (realizable_edge_pp <= 0) and references polymarket_fill_risk for custom sizing.

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 exhaustively discloses behavioral traits: five model families (crypto_price, news_momentum, structural_arbitrage, concentrated_longshot), Kelly calculation, slippage handling, caching at KV level (1h), and diagnostics. It goes far beyond the annotations (readOnlyHint, etc.) by detailing internal logic, Fed bets exclusion, and tradeable-edge knobs. 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 with sections (intro, model families, knobs, response top-level). It front-loads the purpose and then provides detailed explanations. While every sentence earns its place, it could be slightly more concise given the 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 has 9 parameters, no output schema, and complex logic (five models, caching, diagnostics), the description is remarkably complete. It covers models, edge calculations, the by_segment response, knobs, diagnostics, and even why Fed bets are excluded. No gaps are apparent.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds substantial meaning for each parameter: e.g., slippage_pp explains Polymarket's fee structure and suggests adjustments; min_kelly clarifies it skips small opportunities; min_partition_leg_kelly explains partition arbs have zero parent Kelly. This adds significant value beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and the action (return opportunities). However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which slightly reduces clarity.

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

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

The description implies usage for 'what should I bet on today' and mentions that agents can discover opportunities without paging hundreds of markets. It provides knobs for customization but does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage or polymarket_fill_risk. No when-not-to or exclusion criteria are given.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds substantial context: it reads from snapshots, computes trends and decay, identifies expired opportunities, explains gaps, and clarifies that decay is based on daily closes. No contradiction with annotations.

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

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

The description is detailed but well-structured: purpose statement first, then response field explanation, then limits. It front-loads the key question. Every sentence adds value, though length could be trimmed slightly.

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

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

No output schema, but the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and key fields like trend, decay_pp_per_day, lifespan_days. It covers limits and data provenance, making the response fully understandable.

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 existing descriptions. The description repeats the parameters ('days (lookback, default 14, max 30)', 'window (snapshot family, default 1wk)') but adds minimal new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('tracks', 'answers') and clearly states the tool provides 'edge persistence and decay telemetry' and answers a concrete question about edge duration and shrinkage. It distinguishes itself from siblings like `polymarket_edges` by focusing on time-series and trend analysis.

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

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

The description provides context about when to use (e.g., distinguishing fresh vs. old edges) and mentions limits (60-day TTL, decay from daily closes). It does not explicitly state when not to use or name alternatives, but the guidance is clear and sufficient.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details such as ladder walking, returned fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risks (forced directional risk, dominant loss mode), which enrich transparency beyond annotations.

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

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

The description is lengthy but well-structured with clear sections for single-market and basket modes, plus usage guidance. Every sentence adds value, though it could be slightly more concise. The structure aids readability for a complex tool.

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

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

Given no output schema and 4 parameters, the description thoroughly covers input semantics, output fields, and behavioral risks. It explains single-market and basket modes in detail, including return values and warnings, making it complete for correct tool invocation.

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

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

Schema description coverage is 100%, baseline 3, but the description adds significant semantics: explains side defaults (auto for basket), interpretation of size_usd for single vs basket mode, and clarifies market and event parameters. This provides context beyond what the schema alone offers.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishes between single-market and basket modes, and specifies its role relative to sibling tools like polymarket_arbitrage and polymarket_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?

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills create directional risk), providing 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?

Goes far beyond the readOnly/idempotent annotations by disclosing compatibility codes, skipped/unclassified legs, temporal alignment, non-equivalent bet shapes, and the fact that safety fields can be non-empty even when pairs are returned. This is substantive behavioral disclosure that directly affects how an agent should interpret results.

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

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

The description is long but densely organized with labelled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds operational value. The front-loaded definition and structured detail make the length justified.

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

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

With no output schema, the description carries the full burden of explaining the response shape, safety fields, compatibility codes, skipped counters, and temporal alignment. It also cautions about the reliability of pre-mapped pairings, so an agent has everything needed 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 description coverage is 100%, so the baseline is 3. The description reinforces the mutually exclusive use of topic vs explicit ticker/slug and gives concrete examples, but does not add essential semantics beyond what the schema already documents.

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?

Opens with a specific definition: cross-venue spread between Kalshi and Polymarket for the same resolving question, which separates it from Polymarket-only siblings. It further narrows the resource to matched outcome legs and describes two explicit invocation modes.

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?

Clearly differentiates topic-mode shortcuts from explicit custom pairings and warns that pre-mapped topics are often not tradeable because compatibility warnings are common. It does not explicitly name alternative sibling tools, but the context for when this cross-venue tool is appropriate is strong.

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 idempotentHint=true, so the description focuses on scoping ('Scoped to your identifier') and the broader workflow (pairing with remember/forget). This adds useful context beyond annotations without contradiction.

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

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

The description is four short sentences, each adding essential information: retrieval/list mode, use case, scoping, and sibling tools. 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?

For a simple key-value retrieval tool with one optional parameter and comprehensive annotations, the description covers usage, examples, scoping, and integration with siblings. No gaps identified.

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 100% schema coverage and only one parameter, the description explains the effect of omitting the key ('list all saved keys') and gives examples. This builds on the schema's description and provides practical 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 starts with a clear verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes the tool from siblings like 'remember' and 'forget' by explicitly naming the pairing.

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

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

The description provides concrete use cases ('the user's target ticker, an address, prior research notes') and states it avoids re-deriving information. It also notes scoping by identifier. However, it doesn't explicitly say 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?

The description adds behavioral context beyond the annotations by explaining the effect of mark_read: 'set mark_read:true to flag returned events read so the next call only shows newer ones'. It also describes the returned fields and that the same feed is available via a URL. 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 compact yet comprehensive, with each sentence serving a distinct purpose: purpose, returned fields, filtering options, mark_read behavior, and alternative access. It is front-loaded with the primary action and wastes no words.

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

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

Given the tool has 5 parameters and no output schema, the description covers all key aspects: purpose, filtering, mark_read effect, and alternative feed. It lacks explicit error handling or pagination details, but the schema already defines limits. Overall, it 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?

Although the input schema already provides 100% coverage with parameter descriptions, the description adds value by giving examples (type: 'sec_8k') and explaining the behavioral impact of mark_read on subsequent calls, enhancing the schema's bare definitions.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed', using the verb 'pull' with resource 'fired events'. It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on reading, not managing, subscriptions.

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 on when to use the tool, such as filtering by type and since. It also mentions that polling works fine and points to an alternative REST endpoint. However, it doesn't explicitly state when not to use the tool or compare directly to other MCP 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?

Describes data sources, fallback behavior (GDELT→GNews), patent API sunset, and return structure (changes grouped by source, total_changes, citations). Adds value beyond annotations which already mark readOnly/idempotent.

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?

Single well-structured paragraph starts with examples, explains sources, parameter usage, return structure, and sibling distinction. Every sentence earns its place, no fluff.

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

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

Given complexity (multiple sources, fallback, parameter flexibility), description is complete. Covers data sources, since format, return type, and references sibling tool. No output schema but return structure is sufficiently described.

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

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

Schema has 100% coverage. Description adds examples for since (ISO date, relative shorthand), value (ticker or CIK), and type (only company). Provides extra usage 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?

Description clearly states it provides a change feed for a company (SEC filings, news, patents) with example queries. Distinguishes from sibling entity_profile by contrast.

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 when to use this tool ('what's new' queries over a window) and when to use entity_profile instead. Provides guidance on since parameter format.

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

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

Annotations indicate idempotent and non-destructive behavior, which is consistent. Description adds context about scoping by identifier and persistence (authenticated persistent, anonymous 24 hours). Does not mention overwrite behavior, but idempotentHint covers retry safety.

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?

Concise single paragraph with clear structure: purpose, usage, scope, persistence, and companion tools. Every sentence adds value.

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

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

Given two simple parameters and no output schema, the description is complete. It covers functionality, usage, persistence, and companion tools.

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 good descriptions. The description adds value by explaining key-value pair semantics and providing examples of keys, beyond what schema offers.

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 saves data for reuse later, with specific examples (resolved ticker, target address, user preference, research subject). It distinguishes from sibling tools like recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Also mentions pairing with recall and forget, providing clear context.

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

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

The description discloses several behaviors beyond the readOnly/idempotent annotations: graceful degradation if GLEIF/OpenFIGI is unavailable, explicit listing of unresolved identifiers, internal cascading through lookup endpoints, and labeling of identifier sources. These details give the agent a clear model of how the tool behaves, going 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?

Though lengthy, the description is tightly packed with high-value information: example queries, purpose, supported types with detailed identifiers, graceful degradation, and lifecycle context. It is front-loaded with user-facing examples and structured with clear 'SUPPORTED TYPES' sections. Every sentence earns its place.

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

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

The description is comprehensive for a tool with no output schema: it details what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), how unresolved identifiers are handled, input variations (ticker, CIK, ISIN, name), and edge cases (non-US issuers). This covers return values and rare scenarios, making it highly complete.

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

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

The input schema covers both parameters (type, value) with 100% description coverage. The description adds helpful examples (e.g., 'AAPL', 'CH0038863350', 'ozempic') and enriches the value semantics with ISIN-to-LEI explanation, but the schema already conveys the core meaning. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb (resolve) and resource (names to identifiers), and distinguishes itself from sibling tools that focus on deeper research or profiles. Examples of natural-language queries make the purpose immediately understandable.

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 FIRST whenever you have a name but need an ID.' It also notes it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of full differential 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it internally calls ai_visibility_check for each entity, ranks results, and returns a structured output with score, confidence, and signal density. 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 three sentences, each adding distinct value: the first describes what it does, the second how it works, the third when to use it. No redundant or unnecessary words.

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

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

Given the absence of an output schema, the description explains return format (ranked list with score, confidence, signal density). It also covers the internal process and optional parameters. The description is complete for an agent to understand tool behavior and output.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds extra meaning by stating that the first entity in the array is treated as the 'subject' for narrative, which helps an agent understand ordering importance. It also clarifies the role of the context parameter.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility focus and the internal probing mechanism.

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 concrete use case: 'competitive AI-marketing audits: does Claude know about us as well as our competitors?'. While it doesn't explicitly state when not to use or offer alternatives, the context is clear enough for an agent to infer appropriate 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?

Adds context beyond annotations: fans out to two services, partial failures degrade gracefully, first measurement can take 5-30s, sources_failed will list timeout. No contradiction with readOnlyHint etc.

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?

Well-structured and front-loaded, each sentence adds value, though slightly verbose. Still very effective.

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

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

Covers complexity of two APIs, partial failures, timing, ecosystem limitations, and output fields. No output schema needed.

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

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

With 100% schema coverage, description adds valuable details: scoped packages accepted, version defaults to latest, beyond the basic schema descriptions.

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

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

Description clearly states it as a composite check for adding npm packages, specifying verb 'scan' and resource 'dependency', and distinguishes itself from other tools like scan_competitor_ai_presence.

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

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

Explicitly says when to use (agent asks about safety/popularity/size/cost) and when not (non-npm ecosystems have direct deps.dev calls), also mentions partial failure handling.

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

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

Adds significant behavioral details beyond annotations: returns top-N passages with offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and caps input at 200K chars with truncation flag. 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?

Single paragraph of five sentences, front-loaded with purpose. Every sentence provides essential information: purpose, usage, pairing, technical details, and limits. No unnecessary words; perfectly concise.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores). Covers input constraints, embedding details, window size, truncation, and integration with sibling. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances this by explaining the 'text' parameter as the document to search, 'query' as natural-language input, and specifying defaults ('limit' default 5) and constraints (200K char cap). Adds meaningful context beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, specifies the resource (e.g., SEC 10-K body, article) and action (natural-language query). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, ensuring no confusion with other 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 advises using when the record is too large for prompts, saving context and returning only relevant passages. Provides a clear usage context and pairs with a sibling tool, but does not explicitly list when not to use, which is acceptable given the context.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds important behavioral details: requires OAuth account, phone verification for SMS, 10/day cap for SMS, webhook auto-disable after 10 failures, and signature verification. 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 a dense single paragraph that efficiently conveys purpose, prerequisites, types, and delivery options. While every sentence earns its place, it could be slightly restructured (e.g., bullet points) for easier parsing, but it remains concise.

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

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

The description covers most aspects: purpose, prerequisites, type-specific configurations, delivery constraints, and return value. Missing details about error scenarios or exact response format, but given no output schema, the description is reasonably complete for a moderate-complexity tool.

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

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

With 100% schema coverage, the description still adds substantial value by providing concrete examples and detailed explanations for each param type (e.g., sec_8k items, polymarket_edge params, delivery webhook signing secret). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Create', the resource 'proactive monitoring subscription to a live-data event stream', and the outcome 'Returns the new subscription id'. It effectively distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use (proactive monitoring), prerequisites (Pipeworx OAuth account), and supported types with configurations. However, it does not explicitly contrast with sibling tools like recent_alerts or discover_tools, nor does it 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?

Annotations already indicate readOnly, idempotent, openWorld. The description adds that it draws from a live catalog, returns exact tool+argument shapes, and covers all mentions of safety. 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 detailed but front-loaded with common alternative phrasings. It efficiently packs all necessary information, though could be slightly streamlined. Still earns its place.

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

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

For a tool with 1 optional parameter and no output schema, the description covers purpose, usage, output format, and behavioral traits completely. It fully compensates for the lack of output schema by describing the return structure.

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

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

Schema description coverage is 100% and both schema and description explain the 'topic' parameter well. Description adds context on how omitting vs including topic changes the output, going slightly beyond the schema.

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

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

The description clearly states it's an onboarding entry point that returns category-bucketed example questions with exact tool call shapes. It uses specific verbs like 'suggest' and 'returns', and distinguishes from sibling tools like 'ask_pipeworx' by focusing on discovery rather than direct answering.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides context for when to call with no arguments vs with a topic, and implies alternatives when you already know what you want.

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?

Exceeds the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) by adding key behavioral details: ownership checks, deactivation instead of deletion, and preservation of historical data accessible via recent_alerts. No contradiction with annotations.

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

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

Two concise sentences that front-load the primary action and immediately follow with critical behavioral constraints. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the core behavior, ownership constraint, and data lifecycle. Missing return value info (e.g., success/error response) but adequate for selecting and using the tool.

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

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

The input schema has 100% coverage for the single parameter 'id', with a description ('Subscription id (uuid) returned by subscribe.'). The tool description does not add additional meaning beyond what the schema already provides, so baseline score of 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancellation functionality.

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

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

Provides explicit context by stating ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('the row is deactivated (not deleted) so its historical events stay available via recent_alerts'). However, it does not explicitly mention when not to use this tool or alternatives for fully deleting subscriptions.

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/idempotent, but the description adds substantial behavioral context: the dual-path routing, the verdict enum semantics, the critical distinction between could_not_verify (does not support/refute) and unsupported (no source covers it), and the inclusion of verification_error. It also mentions return citation format and reasoning, far exceeding annotation coverage.

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

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

The description is dense but every clause earns its place: usage triggers, path routing, return contract, failure-mode clarification, and efficiency benefit. It front-loads with user-phrase examples and is well-organized despite 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 high tool complexity, the description fully covers return values, verdict meanings, error semantics, and routing logic. It leaves no major gap for an agent deciding to call or interpret results. Annotation-provided safety is already covered.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining tolerance_pct's role as an override of implied tolerance, gives recommended values (1–2 for hallucination detection), and states the default cap at 5. This goes beyond the schema's basic description.

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

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

The description clearly states the tool performs natural-language claim verification with a specific verb ('verify') and resource ('authoritative sources'). It opens with user-phrase examples and distinguishes its scope from siblings by detailing two distinct verification paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else).

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 whenever the agent needs to check whether something a user said is factually correct' and gives context on when the structured vs grounded path applies. It does not name alternatives or state when not to use, but the guidance is clear and practical.

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