Boston 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 behavior not covered by annotations: default model is Workers AI Llama-3.3-70b (free), passing _apiKey incurs direct Anthropic costs, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. This goes beyond the structured metadata.

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

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

The description is two sentences long, front-loaded with the primary purpose, and includes only essential details (default model, cost, output structure, use cases). No redundant wording 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 there is no output schema, the description compensates by specifying the return format. It covers purpose, models, cost, and use cases. It does not address potential failure modes (e.g., invalid _apiKey) or rate limits, but these are minor for a read-only probe tool. Overall, it provides enough context for a typical agent.

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

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

Schema description coverage is 100%, with all four parameters explained. The description adds marginal semantic value by naming the default model specifically ('Workers AI Llama-3.3-70b') and clarifying the cost implication of _apiKey. Since the schema already does heavy lifting, a slight bonus for the extra specificity yields a 4.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource+outcome, distinct from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on visibility scoring rather than Q&A or competitor scanning.

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 use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for an agent to decide. No misleading guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details beyond annotations: it routes to multiple internal tools, fills arguments automatically, returns stable pipeworx:// citation URIs, and emphasizes it's a single fast call. This gives the agent a clear expectation of behavior without contradicting any annotation.

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

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

The description is front-loaded with the 'PREFER OVER WEB SEARCH' directive and packs a large amount of actionable information into a few sentences. While somewhat lengthy, every sentence serves a purpose (use cases, domains, examples, alternatives) and nothing feels redundant.

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

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

Despite lacking an output schema, the description provides a complete picture: what it does, when to use it, what to expect (structured answer with citations), how it relates to alternatives, and example queries. It's sufficient for an agent to invoke correctly and interpret the result.

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

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

The input schema already covers all six parameters (question + five aliases) with descriptions, so baseline is 3. The description adds value by listing example questions that demonstrate appropriate phrasing and scope, but it doesn't elaborate on parameter-specific details 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?

The description clearly states the tool routes questions to one of 5,462 tools across 1,419 verified sources and returns structured answers with citation URIs, distinguishing it from siblings by positioning it as the default entry point and explicitly naming alternatives (ask_pipeworx_grounded, deep_research).

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

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

It explicitly instructs to prefer this tool over web search for factual questions and provides concrete when-to-use triggers ('what is', 'look up', etc.), along with when to step up to alternatives: grounded for verbatim evidence, deep_research for broad questions. This is a model of usage guidance.

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

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

The description goes beyond the annotations by explaining the current experimental state: no candidate is active, so it currently matches ask_pipeworx exactly, yet it is a full working router with no fallback. This clearly discloses the dynamic behavior and potential differences without contradicting the readOnly/openWorld/idempotent hints.

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

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

The description is compact but information-dense: it covers the beta nature, identical scope, current active state, usage guidance, and comparisons in just four sentences. Each sentence contributes essential context without redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers its behavior, current state, relationship to siblings, and usage intent. The absence of output schema is compensated by noting 'same response shape' as ask_pipeworx, making the expected return 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?

The input schema already provides 100% coverage for all parameters, including aliases, so the description doesn't need to add parameter details. It does mention 'same arguments' but that's generic; the schema carries the semantic load, justifying the baseline score.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the same routing purpose, distinguishing it from the stable version by its experimental candidate routing. It states the verb+resource clearly ('Ask Pipeworx Beta') and explains the relationship to siblings without ambiguity.

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

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

Explicit guidance is provided: use it 'exactly like ask_pipeworx when you want the newest routing,' and it notes that results are compared against the stable router. This directly addresses when to choose this tool over the stable alternative, making the choice criterion 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context beyond annotations: it extracts answers using ONLY the tool result, returns verbatim evidence quotes, provides explicit refusal reasons when data doesn't answer, and notes the extra LLM call overhead. It even details the refusal schema. No contradiction with annotations.

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

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

The description is dense but well-structured: it opens with the core value proposition, then explains the mechanism, return format, refusal behavior, usage guidance, and cost trade-off. Every sentence adds necessary information, with no filler. The length is justified by the tool's complexity and the lack of an output schema.

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

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

Given the tool's complexity (routing across 5,462 tools, extraction, refusal modes) and the absence of an output schema, the description is remarkably complete. It describes the success return shape, refusal return shape, all possible refusal reasons, and the cost/usage distinction from siblings. This fully equips an agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for the 'question' parameter, which itself has a complete description ('Your question in natural language. Accepts query, q, prompt, text, input as aliases.'). The tool description does not add parameter-specific meaning beyond mentioning that it 'fills arguments' during routing, which is general behavior rather than parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's specific purpose as a grounded answer mode. It distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding the extraction and refusal behavior, and by explicitly saying to prefer ask_pipeworx for casual lookups. The verb+resource are specific: extract answers from tool results with evidence.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete high-stakes examples. It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'). This directly tells the agent when to use this tool versus the sibling.

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 the description goes far beyond with fan-out behavior, resolver contract, low-confidence short-circuits, status codes, safety warnings, and resolution-rule risk details. This is exemplary disclosure of behavioral traits.

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

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

The description is long but extremely well-structured with uppercase section headers and front-loaded purpose. It's dense with necessary behavioral details for a complex tool; not concise in absolute terms but appropriately organized.

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, so the description must explain return shapes. It dedicates sections to RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, and SAFETY, covering all major return values and edge cases. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context for the market parameter (resolver behavior, examples) but doesn't materially change parameter semantics; depth and include_raw are fully documented in the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input forms (slug, URL, question text) and the classification/fan-out workflow, distinguishing this aggregated research tool from simpler data-pull siblings. The 'Use for' examples further clarify intent.

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

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

The description gives explicit usage examples: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it does not mention when NOT to use this tool or explicitly name sibling alternatives, so it's clear context without exclusions.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds substantial behavioral detail: it names data sources (SEC EDGAR/XBRL, FAERS), explains off-calendar fiscal year handling, specifies the metrics pulled per type, notes results are sorted by primary metric, and mentions 'paired data + pipeworx:// citation URIs per entity.' This goes far beyond the annotations and gives the agent a clear model of the tool's behavior.

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

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

The description is front-loaded with natural language triggers, then a concise statement of the core function, followed by type-specific details, a note on sorting, and the output format. Every sentence contributes meaningful information—no fluff or repetition. It is appropriately sized for the tool's complexity and structured so an agent can quickly grasp the purpose and key edge cases.

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 adequately covers return value semantics ('paired data + pipeworx:// citation URIs per entity') and behavior (sorting, fiscal year handling). It lacks a more detailed breakdown of the response structure, but for a comparison tool with two entity types, the information provided is sufficient for an agent to select and invoke the tool correctly. A 4 rather than 5 because the output format is only sketched.

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

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

The schema already covers both parameters with clear descriptions (enum for type, array with min/max for values), so the baseline is 3. The description adds further semantics by explaining what each type value retrieves (10-K financials for company, FAERS/FDA/trial counts for drug) and gives concrete examples of values ('AAPL','MSFT', 'ozempic','mounjaro'). This enriches the schema without being redundant, elevating the score to 4.

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

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

The description opens with concrete user utterances ('Compare X and Y', 'X vs Y', 'which is bigger / better / larger') followed by a clear statement of functionality: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also distinguishes itself by emphasizing 'ALWAYS PREFER over sequential single-pack lookups' and explicitly states what each entity type (company/drug) retrieves, making it unmistakably different from sibling tools like entity_profile.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it 'Replaces 8–15 sequential lookups,' giving strong when-to-use guidance. However, it does not explicitly mention when *not* to use it (e.g., for a single entity profile) or name a specific alternative tool like entity_profile for those cases, so the exclusion is implied rather than explicit.

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

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

The annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description never contradicts these. The description adds rich behavioral context beyond annotations: account requirements and paid tier details, latency expectations (15-60s, up to ~90s for thorough), behavioral traits like gap recovery, contradiction detection, hop field, semantic excerpting (not head-truncation), and a guarantee that citations are fetchable. It stops short of stating precisely what happens on failure (e.g., rate limits, errors), but the added depth goes well beyond what annotations provide.

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

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

The description is long (about 230 words) but every sentence earns its place, covering purpose, prerequisites, alternatives, behavior, latency, and output characteristics. It is front-loaded with the most decision-critical information (account requirement and alternative tool) and uses formatting (caps, quotes, parentheticals) to aid scanning. It is verbose, but the complexity of the tool justifies the length; no significant waste.

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

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

Given two parameters, no output schema, and rich external context (pricing/plan differences, sibling alternatives, data governance implications), the description is remarkably complete. It explains what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), how long it takes, who can use it, and when to use alternatives. There are no obvious missing behavioral dimensions that would prevent an agent from invoking this tool correctly.

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

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

Schema description coverage is 100%, and the description reinforces the parameter semantics with detail that the schema lacks: it explains what 'depth' levels mean behaviorally (quick=3 facets, standard=5 with gap recovery + contradictions, thorough=8 paid with iterative leads) and clarifies that the question parameter accepts broad/multi-part natural language ('Broad/multi-part is fine — decomposition is the point'). This adds meaningful practical meaning beyond the schema's own descriptions.

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

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

The description opens with a clear verb+resource statement: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call, and immediately distinguishes itself from open-web search and sibling ask_pipeworx. It specifies the exact nature (structured data research, parallel decomposition) and scope, making the tool's purpose unmistakable even among 43 siblings.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and direct alternatives: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and specifically for breaking/current-news topics, prefer ask_pipeworx because deep_research returns mostly empty gaps[]. This is exemplary usage guidance with named alternatives and 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context by explaining that results include 'names, descriptions, and full input schemas (with curated examples)' and that each is 'ready to call directly, no second schema lookup needed.' It also discloses the top-N ranking and the 'Call this FIRST' ordering guidance.

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 at three sentences, each earning its place: the first states the core action, the second lists use-case domains, and the third explains output structure and usage ordering. It is front-loaded with the purpose and avoids redundant or tangential details.

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

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

With no output schema, the description adequately explains the return value as the top-N matching tools with schemas and examples. It also covers practical workflow details like 'no second schema lookup needed' and 'Call this FIRST,' making it self-sufficient for an agent to decide when and how to invoke it. Given the tool's simplicity and good annotations, this is a complete description.

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

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

Schema description coverage is 100% with each parameter (query, q, task, limit, search, description) individually documented, including aliases and an examples array. The description adds a broad context about what the query should describe ('data or task') but does not refer to specific parameter syntax beyond what the schema already covers. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It also lists concrete domains (SEC filings, FDA drugs, etc.) and explicitly positions itself as a discovery tool distinct from siblings that answer questions directly. The instruction 'Call this FIRST... to see the option set' further clarifies its role.

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

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

The description provides explicit when-to-use conditions ('Use when you need to browse, search, look up, or discover') and a strong contextual cue ('Call this FIRST when you have many tools available'). It implies when-not-to-use by saying 'not just one answer,' but does not name specific alternative tools like the get_calls example did, so it lacks full alternative specification.

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 the read-only, open-world, idempotent, and non-destructive nature. The description goes beyond by detailing the data sources and fallbacks (GDELT→GNews, PatentsView sunset soft-fail), the specific return structure, and the 'ONE parallel call' behavior. Though it omits rate limits and auth, those are less critical for a read-only profile tool.

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

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

The description is dense but well-structured: it opens with natural-language examples, states the core value proposition, then lists return components, fallbacks, and input constraints. Every sentence contributes necessary operational detail for a tool with no output schema, and it is front-loaded with the most important usage guidance.

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

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

Given the tool's complexity and absence of an output schema, the description covers the full return payload, data-source fallbacks, sorting order, URI format, input format, and explicit limitations. It equips an agent to set expectations and handle edge cases like names or patent API unavailability, making it contextually 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 already describes both parameters fully, including examples and the 'names not supported' constraint, achieving 100% schema coverage. The description mostly re-emphasizes the same parameter guidance, so it adds limited new semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: building a full cross-source profile of a US public company in a single parallel call. It explicitly lists the return fields (CIK, recent filings, fundamentals, patents, news, LEI) and distinguishes itself from chaining single-pack lookups, as well as from sibling tools like resolve_entity and compare_entities.

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

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

Clear guidance is given on when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an explicit exclusion—names are not supported, and the agent is directed to use resolve_entity first—plus a mention of the patents API sunset and soft-fail behavior.

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

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

Annotations already declare the tool as read-only, non-destructive, and idempotent, so the description's additional details about default 2-week window, normalization, and sorting by date/time provide useful behavioral context beyond the structured metadata.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: source, default window, filters, and output format. No filler or redundancy.

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

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

Given the tool's simplicity, a read-only event lookup with a full schema and annotations, the description covers the essential context: source, default window, filters, and output sort. It lacks explicit mention of pagination or result size defaults, but the schema's limit parameter covers that, so 4 is appropriate.

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

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

The input schema already covers 100% of the parameters with descriptive details (e.g., 'Keyword filter over title, description, and tags'), so the description adds little beyond what the schema documents. It mentions the same filter categories but no new semantic information.

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

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

The description clearly states the tool's function: it returns upcoming Greater Boston events from The Boston Calendar. It specifies the resource (events), source (Boston Calendar), and default behavior (2-week window). This distinguishes it from other tools, none of which are event-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?

The description implicitly provides usage context: it lists the available filters (date range, keyword, free admission) and the default date window, making it clear when to use this tool. No explicit alternatives are given, but the sibling list contains no comparable event tool, so exclusions aren't necessary.

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

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

Annotations already declare destructiveHint:true and idempotentHint:true, covering the safety profile. The description adds usage motivations but does not disclose additional operational details (e.g., behavior if key doesn't exist, confirmation of deletion, permanence). It does not contradict annotations.

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

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

Three short sentences, front-loaded with the core action, followed by usage guidance and sibling pairing. Every sentence earns its place with no redundancy.

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

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

For a simple single-parameter tool with no output schema, the description covers purpose, usage timing, and sibling tools. It could mention return values or lack thereof, but the essential context is present.

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

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

Schema description coverage is 100% since the only parameter 'key' is documented as 'Memory key to delete'. The description does not add extra parameter semantics beyond the schema, aligning with the baseline for high 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-resource pair: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from its siblings 'remember' (store) and 'recall' (retrieve).

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

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

The description explicitly states when to use the tool ('context is stale, the task is done, or want to clear sensitive data') and mentions pairing with 'remember and recall', providing clear context and alternative relationships.

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 the description complements this by disclosing the actual process: fetches page, extracts title/description/key links, emits standard markdown. It doesn't mention failure modes or rate limits, but with rich annotations this is acceptable.

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

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

Two sentences with balanced detail: first defines function and output, second lists concrete use cases. No filler; all information is actionable.

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?

Moderate-complexity fetch/extract/generate tool; description communicates input, transformation, output format, and use cases. It doesn't explain edge cases or how max_links affects output, but output schema isn't required and the overall behavior is 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 covers 100% of parameters with descriptions/defaults; the description adds no extra parameter-specific semantics beyond the overall workflow. Baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Generate a production-ready llms.txt file for any URL'), names the target consumers (AI crawlers), and explicitly outlines three use cases. This distinguishes it from sibling scan/check tools by focusing on file generation rather than 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?

It states when to use it via 'Useful for' with three concrete scenarios, and implies a read-only generation workflow. However, it doesn't explicitly name sibling alternatives or state when not to use it (e.g., if only a quick AI visibility check is needed).

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds value beyond annotations by disclosing the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which is especially important since there is no output schema. No side effects are implied, and the description doesn't contradict annotations.

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

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

The description is two sentences, directly front-loaded with the primary purpose, then returns list, then usage guidance. Every word earns its place with no redundancy or filler.

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

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

For a simple tool with one optional parameter and rich annotations, the description covers the essential context: what it does, what it returns, and when to use it. The absence of an output schema is compensated by listing the return fields, making the description self-sufficient.

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

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

The only parameter, include_inactive, has a fully descriptive schema definition covering 100% of its semantics. The description adds no additional parameter-level information, so per the calibration baseline, a score of 3 is appropriate.

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

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

The description uses a specific verb ('List') and identifies the resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'. It also states the scope (caller's) and the fact that only active ones are returned by default.

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 instructs when to use the tool: 'to review what you're monitoring before adding more' and 'to find an id to cancel'. This directly implies the alternatives (subscribe to add, unsubscribe to cancel) and provides clear context, fulfilling the 'when/when-not/alternatives' criterion.

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

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

Annotations are all false and offer no safety profile, but the description compensates richly: rate limit ('5 per identifier per day'), quota treatment ('doesn't count against your tool-call quota'), human review cadence ('reads digests daily'), and content constraints ('don't paste the end-user's prompt'). All beyond schema/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 longer than average but each section (purpose, use cases, exclusions, content rules, rate limits) earns its place and it is front-loaded with the purpose. Minor verbosity in phrases like 'signal directly affects roadmap' keeps it from a 5.

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

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

Given no output schema, fully false annotations, and nested context objects, the description covers all needed facets: when to use, what to include, what to avoid, rate limits, quota impact, and server scoping. Complete enough for an agent to invoke correctly.

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

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

Schema covers all three parameters at 100%, so baseline is 3. The description adds meaningful message/context nuances by requiring feedback be framed in Pipeworx tools/packs and prohibiting pasted user prompts, which goes beyond schema descriptions.

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

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

The description opens with a specific verb phrase ('Tell the Pipeworx team something is broken, missing, or needs to exist') and names concrete feedback types (bug, feature, data_gap, praise). It clearly distinguishes from sibling tools by scoping to feedback about Pipeworx tools, not general queries.

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

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

Provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data...'), an explicit boundary ('ONLY for tools served by this Pipeworx connection'), and names the alternative action for off-server tools ('file it with that server instead'). This is model 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/idempotent/destructive safety. The description adds valuable behavioral context: 'Cached 5min-1h depending on window', 'derived from CF analytics-engine, no PII', and the output shape '(pack, tool, count)'. This goes beyond annotation basics.

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 reasonably concise and well-structured: a clear lead sentence, followed by return details, use cases, and technical notes. Each sentence adds value, though the use-case list makes it slightly longer than necessary.

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

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

Despite lacking an output schema, the description compensates by explicitly listing what is returned ('top tools, top packs, and total call volume') and the data shape ('(pack, tool, count)'). With a single optional parameter and read-only annotations, this is sufficient for a low-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?

Schema description coverage is 100%, so the schema already explains the window parameter with enum values and guidance. The tool description adds only minor extra context about caching varying by window, which doesn't significantly deepen parameter 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's purpose: 'What other AI agents are calling on Pipeworx right now' and specifies it returns 'top tools, top packs, and total call volume'. This distinctively separates it from siblings like discover_tools or ask_pipeworx by focusing on aggregate trending signal.

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

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

The description provides explicit use cases: '(1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' It lacks explicit when-not-to-use alternatives, but the guidance is clear and context-rich.

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?

Rich behavioral detail beyond annotations: explains monotonicity and partition-sum logic, placeholder filtering, Jaccard similarity threshold, fill check using live CLOB depth at 1000 shares/leg, and warns "realizable_edge_pp ≤ 0 means... do not trade it." The description also exposes response structure and edge cases, adding substantial value.

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

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

The description is front-loaded with a one-sentence purpose, then structured into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). Despite length, almost every sentence adds necessary operational detail or examples. No filler; it is dense but well-organized and scannable.

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

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

Given the tool's complexity and lack of an output schema, the description fully explains return values (opportunities[], partition_check fields, fill check results) and important caveats (realizable edge, thin_legs). It also points to a related tool for custom sizing, making it self-sufficient for correct invocation and interpretation.

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 depth: the event parameter is exemplified with slug formats, the topic parameter is described as a seed question, and the behavior of each mode is elaborated (event mode walks child markets, topic mode flattens related events). It also explains the semantic anchor and partition filter, giving meaning beyond the schema's one-line descriptions.

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

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

The description opens with a specific verb+resource combination: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk, and the two modes (event, topic) are explicitly described with concrete examples.

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

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

Provides explicit when-to-use instructions: "Call with NO args for a trending_scan", "pass event for the strongest per-event partition_check", and "topic for a themed cross-event scan." It also names an alternative tool for related but different use: "For custom sizing use polymarket_fill_risk." This goes beyond vague guidance and includes exclusions and 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?

Despite annotations declaring readOnly, openWorld, and idempotent hints, the description adds substantial behavioral context: 1-hour KV caching, diagnostics for empty segments, the 24h-move warning, and the nuance that partition_overround opportunities have parent-level kelly_fraction_half=0 by design. It also explains how knobs can drop opportunities. 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 front-loaded with the core purpose and well-structured, but it is extremely long, including model family formulas, alpha values, and response segment details that are tangential for tool selection. It is not as concise as it could be, and the length risks overwhelming the reader.

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

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

With no output schema, the description fully explains the return structure (by_segment, fed_candidates/fed_note, _diagnostics) and what each opportunity carries (edge_pp_net, kelly_fraction, liquidity, spread, volume). It also covers knobs, caching, and diagnostics, making it complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining why min_kelly doesn't filter partition_overround (parent-level Kelly is always 0) and by elaborating on slippage_pp with Polymarket fee/depth context. This raises it above baseline.

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

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

The description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' a specific verb+resource with a clear goal. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx vs market price, and orients agents toward 'what should I bet on today.'

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 positions the tool as 'Built for "what should I bet on today"' and explains that it lets agents discover opportunities without paging hundreds of markets. However, it names no specific alternatives or when-not-to-use scenarios, so it falls short of the explicit exclusions required for a 5.

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

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

The description goes far beyond annotations: it details the response structure (tracked[], expired[], snapshot_dates[]), explains trend categories and decay computation, and discloses limitations like the 60-day TTL and gaps in snapshots. This is rich behavioral context that fully informs the agent without contradicting the readOnly/openWorld/idempotent hints.

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

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

The description is dense but well-structured with RESPONSE and LIMITS sections. Every sentence earns its place, front-loading the purpose before diving into details. No fluff or redundancy.

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

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

With no output schema, the description fully explains return values and caveats. It covers history depth, snapshot gaps, decay calculation basis, and gives the context needed to interpret both tracked and expired opportunities. For a 2-parameter tool, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context ('lookback', 'snapshot family') but mostly repeats what the schema already states (defaults, ranges, allowed values). It does not significantly enhance the schema's parameter meanings.

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

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

The description opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the core question 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (which likely computes edges) and polymarket_arbitrage.

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?

Clear context is provided: it is used to determine edge age and decay, with the illustrative contrast 'a fresh wide edge and a 3-week-old wide edge are different trades.' However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already mark readOnly/idempotent, but description adds behavioral depth: 'walks the ladder', returns verdicts, and warns that 'partial basket fills convert an arb into an unhedged directional position'. No contradiction with annotations.

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

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

The description is long and dense, but every sentence provides necessary detail for a complex tool. It is front-loaded with a summary and uses clear mode markers (SINGLE-MARKET, BASKET), though it could benefit from better visual structure.

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

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

With no output schema, the description enumerates all returned fields per mode, explains risk scenarios, and provides actionable context. It is thorough enough for an agent to correctly invoke and interpret 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%, so baseline 3. Description adds crucial exclusivity ('REQUIRES one of market or event') and clarifies interpretation of size_usd and side per mode, though much of this is also in the schema.

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

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

Description clearly identifies the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', explicitly naming its two modes (single-market and basket). It distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges as tools to precede.

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

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

Provides explicit usage guidance: '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 on thin books is not capturable, partial fills cause unhedged risk), giving both when and why.

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 tool's read-only, idempotent nature is already declared by annotations, but the description goes beyond by detailing safety fields: compatibility_warning conditions (matched_pairs:0 vs skipped_cross_type), temporal_alignment, and skipped_cross_type/subtype counters. It even warns that pre-mapped ≠ tradeable, giving honest behavioral disclosure. 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 using 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' markers, with each paragraph serving a distinct purpose. It front-loads the core definition and then layers operational detail. A few redundant phrases could be trimmed, but overall it earns its length.

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

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

With no output schema, the description thoroughly covers the response format (leg-by-leg prices, spread computation, top_spreads_pp) and warning signals. It also addresses temporal alignment and skipped pair counters, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, and the description enriches parameter semantics by explaining the two modes: topic auto-fetching and explicit overrides. It clarifies the relationship between parameters (e.g., kalshi_event_ticker overrides the topic-mapped side) and provides examples in the schema. This adds conceptual meaning beyond the raw property 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 defines a cross-venue spread tool whose scope (Kalshi vs Polymarket for the same resolving question) is specific and distinct from sibling tools like polymarket_arbitrage. Although it lacks an imperative verb, 'Cross-venue spread' together with the two-mode explanation makes the purpose unmistakable.

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

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

The description explicitly explains when to use this tool: for comparing pricing between the two venues, and it offers two modes of invocation. It also provides cautionary guidance by stating most pre-mapped topics return compatibility_warning today, which helps the agent set expectations. However, it doesn't name alternative tools for when this tool is inappropriate, so it's a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond that: scoping to an identifier (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieve vs. list. It doesn't mention what happens when a key is absent, but the annotation coverage lowers the bar and the added scoping detail earns a 4.

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

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

Three sentences, front-loaded with the core action, followed by use-case examples and scoping. Every sentence adds value without redundancy, and the structure logically flows from action to context to integration.

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

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

With a single optional parameter and no output schema, the description fully covers both invocation modes (retrieve vs. list), the data source (via remember), the scoping constraint, and relationships to siblings. It is complete for an agent to use effectively.

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

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

Schema coverage is 100% and the schema description already explains the key parameter and the omit-to-list behavior. The description reinforces this but adds no new parameter-level details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses specific verbs ('Retrieve', 'list') and a clear resource ('value previously saved via remember', 'all saved keys'). It distinguishes itself from sibling tools by explicitly naming remember and forget, making the tool's role in the memory trio unambiguous.

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

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

Provides clear guidance: use it to look up stored context ('user's target ticker, an address, prior research notes'), omit the key to list, and explicitly pairs with remember (save) and forget (delete). This tells the agent when and how to use the tool, and contrasts it with alternatives.

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

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

The description claims 'readOnlyHint' is true, but explicitly describes mark_read:true as flagging returned events as read and altering future call results. This directly contradicts the readOnlyHint annotation. The description also reveals state mutation, making the annotation misleading.

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 deliver all key information without redundancy. It front-loads the core action and return payload, then covers filtering, mark_read behavior, polling suitability, and an alternate access method.

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 conveys the return payload, filter parameters, side-effect of mark_read, polling guidance, and an alternative endpoint. There is no output schema, so the explicit return-field list is helpful. The only gap is the unresolved contradiction with readOnlyHint, which is more about transparency than contextual 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?

Schema coverage is 100%, but the description adds valuable semantics beyond schema names: type is exemplified with 'sec_8k', since is specified as ISO timestamp, and mark_read's effect on future calls is explained. It does not address 'limit' or 'unread_only', but the schema already describes those.

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 a subscription feed and returns recent alerts. It specifies what each event carries (source, citation_uri, raw payload) and distinguishes from generic 'events' by focusing on the evaluator-written persisted feed.

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

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

Provides explicit usage guidance: filtering by type and since, using mark_read to advance the feed, and notes that polling is acceptable. It also mentions an alternative GET endpoint for scripts/dashboards, though it does not compare against sibling tools like 'events'.

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 detailed behavioral traits beyond annotations: it fans out to SEC EDGAR, GDELT→GNews fallback on rate limits or 5xx, and USPTO patents with a noted soft-fail due to PatentsView API sunset. It also mentions returns (structured changes[], total_changes, pipeworx:// URIs), providing transparency about output shape and potential limitations.

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

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

Though moderately long, the description is information-dense with no fluff. It front-loads user-intent queries, then logically flows through sources, parameter syntax, return structure, and the alternative tool. Every sentence earns its place, and the use of em-dashes and semicolons keeps it readable.

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

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

For a multi-source tool with no output schema, the description is remarkably complete: it covers all sources, fallback logic, parameter formats, return values, and a known limitation (USPTO soft-fail). It even gives an alternative for static profiles, leaving no critical gaps for the agent to infer.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for `since` ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also contextualizes how `value` (ticker or CIK) maps to sources, enhancing the schema's bare descriptions.

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

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

The description explicitly states 'change feed for a company in the last N days/weeks/months' and leads with concrete example queries like 'What's new with X' and 'updates on Acme'. It also distinguishes itself from sibling entity_profile by clarifying that entity_profile is for static profiles, while this tool focuses on changes.

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?

Clear guidance is provided on when to use this tool versus alternatives: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also explains the parallel nature and source fallback behavior, helping the agent decide based on latency and data needs.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context beyond this: storage as a key-value pair scoped by identifier, persistence differences for authenticated vs anonymous sessions (24 hours), and the pairing with recall/forget. No contradiction with annotations, and the added details help set expectations.

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

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

The description is slightly longer than the minimum needed, but every sentence contributes meaningful context: purpose, usage triggers, storage model, retention policy, and companion tools. It is well-structured and front-loaded with the core purpose. No filler or redundancy.

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

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

For a simple two-parameter tool with good annotations, the description covers the essential aspects: what data to store, when to use it, persistence rules, and links to related tools. It does not describe return values or error scenarios, but the absence of an output schema makes that less critical. Overall it is complete enough for safe and correct usage.

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 key and value, so the schema already carries the parameter meaning. The description adds illustrative examples and clarifies 'value' accepts any text, but this does not significantly extend the schema's explanation. Baseline 3 is appropriate since the description reinforces but doesn't compensate for missing schema 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 states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address, user preference) and explicitly distinguishes itself from sibling tools by naming recall and forget. This goes beyond a simple verb+resource to convey a distinct role.

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

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

The description gives explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also states exclusions and alternatives by directing to 'recall to retrieve later, forget to delete,' effectively providing usage boundaries.

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 a safe, idempotent read operation, and the description adds useful context by disclosing internal cascading lookups, auto-disambiguation, and the exact return values (ticker, CIK, company_name, RxCUI, ingredient, brand, plus citation URIs). It does not contradict the annotations and enriches the behavioral model.

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

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

The description is well-structured with a clear opening, example phrases, a directive sentence, and a detailed breakdown of supported types. It is somewhat long but every sentence serves a purpose; the structure is front-loaded and effective, though minor redundancy exists between the two type descriptions.

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 provides comprehensive return information for each entity type, including citations and input variants. It also covers the internal cascade and the tool's role as a replacement for manual lookups. It does not address failure modes or edge cases beyond auto-disambiguation, but the scope is well 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?

The input schema already provides full descriptions for both parameters, including the enum for type and examples for value, so the baseline is 3. The description adds example values and return details, but does not reveal any parameter behavior beyond the schema. It is adequate but not additive.

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: resolving user-spoken names to canonical official identifiers (ticker, CIK, RxCUI). It includes concrete example queries and distinguishes itself as the first step when an ID is needed, making it distinct from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear usage heuristic. It also explains that it replaces 2-3 manual lookups, giving efficiency context. However, it does not explicitly name alternative tools or state when not to use it, but the guidance 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?

With annotations already declaring readOnly/idempotent/non-destructive, the description adds meaningful behavior: it invokes ai_visibility_check per entity, ranks results, and returns specific metrics (score, confidence, signal density). This goes beyond annotation coverage without contradicting it.

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

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

Three tight sentences, first sentence states purpose immediately, no redundant filler. Every clause adds information about mechanics, use case, or output.

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 schema fully documents parameters and the description explains output format and use case, no critical gaps remain. It doesn't mention rate limits, but annotations cover safety, and no output schema is expected.

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 all four parameters are well-documented. The description's mention of 'your brand + N competitors' slightly enhances the entities semantics but doesn't add beyond schema's explicit first-entity-subject note, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities and details the mechanism (probes each with ai_visibility_check, ranks by score). It distinguishes itself from single-entity ai_visibility_check by focusing on side-by-side comparison.

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

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

It provides a clear use case ('competitive AI-marketing audits') with an example query. However, it doesn't explicitly state when not to use it or name alternatives like compare_entities, 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?

Beyond the read-only/idempotent annotations, the description discloses important behavior: partial failure degradation (bundlephobia timeout, sources_failed field), latency (5-30s for first measurement), and the detailed return structure (summary block, per-advisory detail, links, alternatives). This gives the agent a clear picture of what to expect.

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

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

The description is dense but every sentence contributes value: purpose, use cases, output fields, scope, and failure handling. It is slightly long, but the complexity of a composite tool justifies the length. The purpose is front-loaded in the first sentence.

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

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

For a tool with no output schema, the description enumerates all key output fields, covers ecosystem scope, communicates latency and partial failure behavior, and provides clear usage guidance. No significant missing context is 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?

The input schema already fully describes both parameters (package name with scoped support, version with default). The description adds little new parameter information, so the baseline 3 applies for 100% schema coverage.

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

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

The description clearly states the tool is a composite npm package evaluation check ('should I add this npm package to my project'), listing specific data sources (deps.dev, bundlephobia) and output components. It distinguishes from sibling tools by focusing on npm package safety/size/popularity, unlike AI visibility or market spread 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?

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states exclusions: NPM-only in v1, with other ecosystems falling under deps.dev:version directly, which tells the agent when not to use this tool.

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

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

Annotations already say readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description goes further: it discloses the truncation cap (200K chars, flagged), the return format (passages with character offsets and similarity scores), and the internal mechanism (BGE-base-en embeddings, cosine, 500-char overlapping windows). This is rich, non-obvious behavioral detail with no contradiction.

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

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

The description is front-loaded with the core purpose and then expands with use-case, output format, companion tool, and technical details. Each sentence serves a purpose; the length is justifiable for the amount of valuable context, though it is slightly longer than the leanest examples.

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

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

Given there is no output schema, the description fully covers what the agent needs: the return shape (passages, offsets, scores), an edge case (truncation), and the integration with ask_pipeworx_grounded. It also clarifies the input source (fetched record), making the tool self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: text is described as 'already pulled' with document examples, query is implied with natural-language phrasing, and 'top-N passages' clarifies the limit parameter. This adds a layer beyond the schema's basic descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb+resource statement that immediately distinguishes this tool from knowledge-base wide searches. It explicitly contrasts with ask_pipeworx_grounded, and provides concrete examples (SEC 10-K body, article) that clarify the intended input.

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 gives an explicit condition for use: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and integration guidance.

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

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

The description goes far beyond annotations by disclosing authentication constraints (anonymous/BYO cannot persist), delivery channel caveats (SMS cap, webhook auto-disable after 10 failures, one-time signing secret), and the always-on feed behavior. These are non-obvious behavioral traits that an agent needs to know, and none contradict the annotations.

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

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

The description is a single dense paragraph that front-loads the primary action and return value, then systematically covers types and delivery channels. Every sentence adds value, with no filler or repetition of schema information. The use of examples and parentheses keeps it compact for the amount of detail conveyed.

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 nested objects, multiple subscription types, and delivery options, the description covers all critical aspects: return value, authentication prerequisite, type-specific parameters, delivery channel behavior (feed always on, email, SMS with verification and cap, webhook with signing and auto-disable). No output schema exists, so the mention of the returned subscription id satisfies the need for return-value transparency. This description is complete enough for an agent to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds semantic meaning beyond the schema. For example, it explains that items:["5.02"] means officer change and provides concrete examples for each type (e.g., topic:"fed", series_id:"UNRATE"). This helps an agent construct valid parameters, going beyond the schema's bare parameter list.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb and resource that clearly distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also states the return value (new subscription id), leaving no ambiguity about the operation.

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

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

The description provides strong contextual guidance by stating the OAuth requirement, listing supported subscription types with examples, and describing delivery channels. It does not explicitly name alternatives (e.g., 'use list_subscriptions to view existing subscriptions'), but the prerequisites and use cases are clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds useful context about the live catalog dynamic, the category bucketing, and that it returns exact tool+argument shapes—beyond what annotations state.

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

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

The description is long but well-organized: starts with example queries, then the core purpose, then parameter usage. Each sentence adds value, though it could be slightly tightened. It is front-loaded with the most important information.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and return behavior. It is fully self-contained for an agent to decide when and how to invoke it.

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

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

Schema covers the parameter with a description of allowed values, but the description enriches it by giving concrete examples ('finance', 'pharma', 'betting') and explaining the behavior when omitted ('cross-category spread'). This is meaningful added value.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings like discover_tools by positioning itself as the 'use FIRST' tool for new agents and by specifically mentioning meta-tools.

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

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

Explicitly says when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on optional topic filtering and the no-argument default, giving clear invocation context.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds 'in use' and 'with counts' but does not disclose sorting order, pagination, or other edge cases. This adds some value beyond annotations but not rich behavioral context.

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

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

A single sentence that is front-loaded with the main verb and resource, contains no filler, and clearly communicates purpose and use case.

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

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

The tool is a simple one-parameter list operation with rich annotations and full schema coverage. The description explains what it does and why it's useful, making it complete for this complexity.

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

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

The schema fully documents the single 'limit' parameter with a description, giving 100% coverage. The tool description does not add parameter-specific information, so baseline 3 is appropriate.

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

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

Description states 'List the event tags/keywords... with counts', a specific verb and resource with clear scope. It distinguishes itself from the sibling 'events' tool by focusing on tags as filterable facets.

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 'useful as filterable facets for the events tool', which implies when to use it (to get tags for filtering events). It doesn't name alternatives explicitly but the context is clear and there are no exclusions.

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

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

The description discloses ownership enforcement, deactivation rather than deletion, and that historical events remain available. These details go beyond what annotations provide (readOnlyHint, destructiveHint, etc.), giving the agent important side-effect information without contradicting any annotations.

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

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

The description is two sentences, front-loaded with the primary action ('Cancel a subscription by id') and followed by a concise, high-value caveat. Every word contributes, with no redundancy or filler.

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

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

For a simple tool with one parameter and no output schema, the description covers all essential aspects: purpose, ownership constraint, and the non-destructive deactivation behavior. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already documents the sole parameter 'id' with a clear description and its source ('returned by subscribe'), giving 100% coverage. The description does not add further parameter-level meaning, so the 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 uses the specific verb 'Cancel' and identifies the resource as 'a subscription by id', making the action immediately clear. It also distinguishes the tool from siblings like subscribe and list_subscriptions by clarifying the deactivation (not deletion) behavior, ensuring no ambiguity.

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

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

The description provides clear context: the tool is used to cancel subscriptions owned by the caller, and it notes the soft-delete behavior. However, it does not explicitly name alternatives (e.g., list_subscriptions) or state when not to use it, though the context strongly implies the appropriate use case.

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

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

Beyond the annotations that already declare readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral detail: the routing logic (SEC EDGAR + XBRL vs. grounded pipeline), the percent-delta math, the verbatim evidence citation, the list of possible verdicts, and the promise to replace 4–6 sequential calls. 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 densely packed and front-loaded with example phrasings and use-case triggers. It is somewhat long (about 110 words) but every sentence earns its place by covering the main workflow, return values, and two distinct execution paths. Slightly overlong for a tool description, but structure is logical and 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 complexity (two execution paths, multiple verdicts, evidence citation), the description is remarkably complete: it states what the tool does, how it routes claims, what it returns, and what it replaces. No output schema exists, so the description carries the burden of explaining return values, and it does so explicitly.

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 itself does not add significant parameter-level detail beyond what the schema already provides; the schema richly describes 'claim' and 'tolerance_pct' including ranges, defaults, and use cases. The description's mention of 'exact percent-delta math' and 'tolerance' adds minor context but does not elevate beyond baseline.

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

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

The description clearly identifies the tool as a claim verifier with specific verb ('verify'), resource ('natural-language claim'), and scope ('against authoritative sources'). It distinguishes itself from siblings by explicitly mentioning the SEC EDGAR / XBRL fast path for financial claims and a grounded pipeline for other claims, and by enumerating example user phrasings that signal when to invoke it.

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

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

The description states explicitly 'Use whenever the agent needs to check whether something a user said is factually correct' and provides a decision heuristic (financial vs. other claims). It does not name specific sibling alternatives or give when-not-to-use guidance, but the context is clear enough to guide selection among the 30+ sibling tools.

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