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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: it routes to 5,439 tools, returns stable pipeworx:// citation URIs, and emphasizes a single fast call. This covers operational behavior without contradicting annotations.

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

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

The description is long but every sentence contributes: preference, routing, citations, use cases, examples, and alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured with clear usage signals. Slightly dense but not wasteful; earns a 4.

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

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

With no output schema, the description compensates by stating the return format: 'structured answer with stable pipeworx:// citation URIs.' It covers what the tool does, when to use it, when not to (step up to alternatives), and provides multiple examples. Complete for the complexity of 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 the baseline is 3. The description adds value by giving concrete example queries ('current US unemployment rate', 'Apple's latest 10-K') and broad domain categories (SEC filings, FDA drug data, sports, etc.), which help the agent formulate valid questions beyond the schema's generic 'question' description.

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

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

The description clearly states the tool's purpose: answering factual questions about current/historical data with authoritative structured data and citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different scenarios, and positioning itself as the default entry point.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' It also gives clear step-up conditions for alternatives (ask_pipeworx_grounded, deep_research) and notes that it works on every tier.

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

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

The description adds significant behavioral context beyond the annotations by disclosing that candidate routing improvements are enabled live when under test, that no candidate is currently active (matching ask_pipeworx exactly), and that it is a full working router with no fallback. This complements the readOnly/idempotent/openWorld annotations without contradiction.

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

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

The description is a compact four-sentence paragraph where every sentence adds value: identity, current state, usage guidance, and a reassurance about its functionality. It is front-loaded with the key beta designation and contains no filler.

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

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

For a routing tool with no output schema, the description adequately covers its purpose, relationship to ask_pipeworx, usage context, and current experimental status. The phrase 'same response shape' sets expectations for return format, and annotations cover safety characteristics.

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 covers all parameters with 100% coverage, listing 'question' and its five aliases. The description only references 'same arguments' without adding any additional parameter meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router with the same 5,439 tools and arguments, and highlights its experimental nature. It distinguishes itself from the stable ask_pipeworx sibling by mentioning candidate routing improvements and being the 'experimental edge.'

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

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

It explicitly instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router, providing a clear use case and an implicit alternative. This gives direct when-to-use guidance without ambiguity.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive hints, the description reveals concrete behaviors: it 'EXTRACTS the answer using ONLY what the tool result contains', produces an explicit refusal with five possible refusal reasons, and costs one extra LLM call. No contradiction with annotations exists.

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

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

The description is longer than ideal but every sentence carries operational value: it explains the grounded extraction mechanism, the return/refusal shapes, use-case boundaries, and trade-off versus the sibling tool. It is front-loaded with the core purpose and remains structured, though a slight trim would earn 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?

There is no output schema, so the description compensates by fully defining the success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal shape with all possible refusal reasons. It also covers routing, cost, and use-case guidance, making the tool fully operable without additional context.

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

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

Schema coverage is 100%, so all six parameters are documented with descriptions, and the schema already clarifies that q, text, input, query, prompt are aliases for question. The description adds no parameter-specific guidance 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 names a specific verb ('ask') plus resource ('Pipeworx') and clearly distinguishes this grounded mode from the sibling 'ask_pipeworx' by emphasizing hallucination resistance and explicit refusal behavior. It positions the tool as an answer-extraction mode over the same routing, making its unique scope 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 states when to use the tool ('high-stakes reads', 'quoted, cited, or acted on', 'must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also references the same routing as ask_pipeworx, making the alternative explicit.

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

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

Annotations already declare 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 description provides rich behavioral context far beyond the annotations: it discloses that the tool never invents answers (explicit gaps[]), that it decomposes into facets and routes in parallel, that it performs iterative hop recovery at certain depth levels, that large records are semantically excerpted (not head-truncated), and it gives expected latency (15-60s, up to ~90s for thorough). It also explains the return packet contents (verbatim evidence, confidence, source, fetched_at, citations, hop field, contradictions[]). Annotations declare readOnly/destructive/idempotent/openWorld hints, and the description complements rather than contradicts them, adding meaningful value about what the tool actually does internally.

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

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

The description is long but every sentence earns its place by conveying critical decision-relevant information (account requirement, scope boundaries, depth semantics, latency expectations, output structure, sibling differentiation). It is front-loaded with the most urgent operational detail (ACCOUNT REQUIRED) and uses concrete examples. It is somewhat dense and could be tightened, but given the tool's complexity (dual-parameter semantics, multiple depth modes, distinction from siblings), the length is justified. One structural improvement might be bolding key terms, but the current structure is acceptable.

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 high complexity (2 params with enum, no output schema, no nested objects), the description carries full burden for return-value and behavior explanation. It fully explains what the findings packet contains (verbatim evidence + confidence + source + fetched_at + citation), the gaps[] and contradictions[] fields, and the semantic excerpting behavior. It also covers prerequisites (account/sign-in), latency, and alternatives. This is a complete picture for an agent to decide whether to invoke this tool and what to expect from 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 coverage is 100% (both question and depth are documented), so the baseline is 3. The description adds meaningful depth semantics that go beyond the schema: it explains the behavioral trade-offs of each depth level (quick=single hop, standard=gap recovery + contradictions, thorough=adds iterative lead-chasing and requires paid plan), and clarifies that depth:'standard' is the default though not marked as such in the schema. The question parameter is adequately explained both in schema and description ('Broad/multi-part is fine — decomposition is the point'). Minor credit beyond baseline because the description clarifies the real-world consequence of choosing each enum 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 identifies deep_research as a grounded multi-source research tool over Pipeworx's 1412 structured data sources, explicitly distinguishing it from open-web search and single-lookup tools. It lists concrete example use cases ('compare X and Y's regulatory + financial exposure') and a clear verb+resource+scope: 'Decomposes your question... routes each [facet] to the right tool... returns a findings packet.' This makes the purpose unambiguous and well-differentiated from siblings.

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

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

Usage guidance is explicit and actionable. It states when to use this tool (broad/multi-part structured-data questions), when NOT to use it (single lookup: use ask_pipeworx; breaking/colloquial current-news: prefer ask_pipeworx because deep_research returns empty gaps[]), and names the alternative tools. It also explains depth-level selection (standard vs thorough for multi-step questions) and account requirements, including a fallback for unsigned-in users. This is exemplary when-to-use vs when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context, disclosing that each call cascades through several lookup endpoints internally, and explains the return format for each entity type (e.g., ticker + CIK for companies, RxCUI for drugs). This goes beyond the annotations.

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

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

The description is well-structured with a clear query examples opening, then 'SUPPORTED TYPES' section. It is detailed yet every sentence adds value, covering use cases, return values, and internal behavior without unnecessary fluff. The length is justified by the tool's complexity.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns for each type, including specific fields and citation URIs. It also notes the cascading internal lookups and the tool's role as a preliminary step. This makes the description complete for an agent to understand invocation and expected results.

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

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

Schema coverage is 100%, but the description significantly enhances parameter understanding. It explains the 'type' parameter's allowed values and what each returns, and for 'value' it provides format examples (ticker, CIK, brand/generic name) and disambiguation behavior. This is far more informative than the schema alone.

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

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

The description clearly identifies the tool's purpose as resolving user-spoken names to canonical/official identifiers. It provides concrete query examples ('What's the ticker for…' / 'find the CIK for…') and states that other tools require these identifiers as input. This distinguishes it 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 gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, strengthening the use case. However, it does not specify when NOT to use it or mention alternatives, such as entity_profile for detailed entity information after resolution.

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.