Montreal Events

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

Annotations already confirm read-only, idempotent, non-destructive behavior. The description adds valuable context: default model details, optional Anthropic probing with BYO key, and the shape of the return value (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

The description is two sentences followed by the return structure list. It is front-loaded, concise, and contains no extraneous information. Every sentence earns its place.

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

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

Given no output schema, the description explains the return format (per-model result + combined view). However, it omits details on what 'signals' or 'raw_response' contain. For a moderate-complexity tool, it is largely complete but leaves minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters adequately. The description adds minor value by clarifying default model and BYO key, but does not significantly enhance meaning beyond the schema.

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

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

The description clearly states the verb 'probe' and 'score' and the resource 'LLMs for a business/brand/product/topic'. It differentiates from sibling tools by its specific focus on AI visibility scoring, which is unique among siblings like ask_pipeworx or compare_entities.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides guidance on model selection (default vs. Anthropic). However, it does not explicitly exclude any scenarios or compare to sibling tools, lacking '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?

The description goes well beyond the annotations by disclosing that the tool internally routes to thousands of downstream tools, fills arguments automatically, and returns structured answers with stable citation URIs. This aligns with the readOnlyHint, openWorldHint, and idempotentHint annotations, and there is no contradiction. It does not fully disclose potential failure modes or the exact citation format behavior, but the added context is substantial.

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 dense and well-structured. It front-loads the most important directive ('PREFER OVER WEB SEARCH'), then lists domains, explains the routing mechanism, gives trigger phrases, and provides six concrete examples. Every sentence contributes; it is slightly longer than necessary but not padded, so it earns a 4 rather than 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?

For a single-required-parameter tool with no output schema, the description adequately covers input (natural-language question), processing (routing, argument filling), and output (structured answer with citations), plus a wide range of use cases. The only minor gap is that it does not explain how agents should interpret or cite the pipeworx:// URIs, but that is beyond the minimum needed for correct invocation.

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

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

The input schema provides 100% coverage: all six parameters are documented as aliases for 'question', and the main 'question' parameter has a thorough description. The tool description adds examples and usage triggers but no additional parameter-level semantics. Per the calibration, baseline 3 is appropriate when the schema already carries the semantic burden.

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 routes natural-language questions to one of 5,743 tools across 1,500 verified sources and returns structured answers with pipeworx:// citation URIs. The verb 'routes' and the resource 'question' are explicit, and the description distinguishes itself from web search by saying 'PREFER OVER WEB SEARCH' and listing concrete data domains. However, it does not explicitly distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it falls short of a 5.

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 when-to-use guidance: it says 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions', with explicit trigger phrases and examples. It does not, however, mention alternative tools such as deep_research or ask_pipeworx_grounded, so there are no explicit when-not-to-use or alternative-routing instructions beyond the preference over web search.

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 include readOnlyHint and idempotentHint, but the description adds critical context: it is an experimental beta with candidate routing improvements enabled live, no candidate is currently active, and it matches ask_pipeworx exactly right now. It also clarifies this is a full working router, not a fallback stub.

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 front-loaded with the core purpose. Each sentence adds useful context about the beta state and current behavior, though the triple restatement of 'same arguments, same response shape' is slightly redundant.

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

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

For a tool with no output schema, the description covers everything needed: what it is, how it differs from the stable sibling, when to use it, the current inactive candidate state, and the response shape. An agent can confidently invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents the parameter aliases. The description restates that arguments are identical to ask_pipeworx but adds no new parameter-level semantics beyond what the schema provides.

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

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

The description states the tool is the beta version of ask_pipeworx with the same universal router, same 5,743 tools, same arguments, and same response shape. This clearly identifies the verb ('ask') and resource ('pipeworx beta') and differentiates it from the stable ask_pipeworx sibling.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It implies the stable alternative for non-experimental use, though it doesn't explicitly state 'don't use this for stable requests'.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral detail: it returns only grounded evidence, includes refusal_reason variants, never fabricates when data is missing, and costs an extra LLM call. There is 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?

Although longer than average, every sentence carries load-bearing information: the grounded mode, mechanism, success/refusal return shapes, concrete use cases, and cost-based alternative. The key differentiator is front-loaded, and the structure is logical.

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 fully by enumerating the success payload, the refusal payload, all five refusal reasons, usage guidance, and cost consideration. An agent has all necessary context 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 fully documents the question parameter and its aliases (100% coverage), so the description does not need to restate parameter details. The description adds no extra parameter nuance beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly identifies a distinct mode ('hallucination-resistant answer mode'), explains the core mechanism (routes like ask_pipeworx, then extracts the answer only from the tool result), and differentiates this tool from the sibling ask_pipeworx by adding evidence and explicit refusals. It is precise about the resource and behavior.

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

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

It explicitly states when to use the tool ('Use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), also naming the alternative tool. The high-stakes condition and cost tradeoff give concrete selection criteria.

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

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

Beyond the annotations (readOnly, idempotent), the description extensively discloses behavior: resolution process, fan-out patterns, response shapes, edge cases (low-confidence short-circuit, closed markets, illiquid spreads), and rule-risk analysis. It even explains the resolver contract and parent-event extractor. No contradictions with annotations; the description greatly enriches the agent's understanding.

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

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

While the description is long, it is extremely well-structured with clear headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and every sentence adds necessary information. There is no redundancy. The length is appropriate for the tool's complexity, and the structure makes it easy for an AI agent to parse.

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 thoroughly covers all critical aspects: market resolution, classifier selection, evidence sources, response fields, safety mechanisms, and rule-risk. It addresses potential pitfalls (low-confidence matches, closed markets, wide spreads) and provides actionable guidance. The tool's complexity is fully addressed.

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 for the market parameter by specifying three valid formats (slug, URL, question text). For depth and include_raw, the description does not add beyond the schema's documented defaults and behavior, but the extra context for market justifies a point 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 opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on general research and data retrieval. Additional context about classifiers and response shapes reinforces the tool's specific 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?

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also gives detailed guidance on when to inspect market_match_confidence, parent_event fields, and cancellation rules, effectively telling the agent when to trust results and when to be cautious. This covers both usage and exclusion.

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

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

Annotations already indicate read-only and idempotent behavior; description adds parallel execution, off-calendar fiscal year handling, FAERS source for drugs, sorting by primary metric, and citation URIs—significant added 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?

Description is front-loaded with trigger phrases and covers all necessary aspects without fluff. Slightly lengthy but each sentence adds value; could be marginally tighter.

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

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

Covers inputs, behavior, and output (paired data + citation URIs). No output schema exists, but description implies structured results. Adequate for the 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%, but description enriches by explaining the value format (tickers/CIKs for company, drug names for drug) and the max items constraint, adding clarity 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 lists natural language triggers ('Compare X and Y', 'X vs Y'), specifies the action as side-by-side comparison of 2-5 entities, and distinguishes from siblings by noting it replaces multiple sequential lookups.

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

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

Explicitly states to prefer this over sequential lookups when comparing entities, and details the two type options and their data sources. Lacks explicit 'when not to use' but context is clear enough.

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

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

The description adds extensive behavioral context beyond the annotations: it requires an account, notes paid-tier limitations, states the tool is NOT open-web search, discloses that it never invents answers and returns explicit gaps[], explains the hop and contradiction behavior across depth levels, clarifies that citations are only included when resolvable, describes semantic excerpting, and provides expected latency ranges. The annotations are fully consistent, and the description greatly enriches them.

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

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

The description is long and dense, but nearly every sentence carries useful information: auth routing, capability boundaries, output composition, depth semantics, citation fetchability, and performance expectations. It is front-loaded with the account requirement and routing alternative before diving into mechanics. It could be tightened, but the length is justified by the complexity of the tool and the absence of an output schema.

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

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

With no output schema, the description fully carries the burden of explaining return behavior, and it does so thoroughly: it lists the findings packet fields, describes gaps[], contradictions[], hop fields, citation URIs, fetchability guarantees, excerpting behavior, and time expectations. It also covers auth, pricing, and sibling routing. An agent has everything needed to invoke the tool correctly and interpret its output.

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

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

Schema coverage is 100%, so the schema already explains both parameters well. However, the description adds real value: it clarifies that 'question' is expected to be natural language and broad/multi-part, and it expands on 'depth' by linking quick/standard/thorough to facet counts, hops, gap recovery, contradiction scans, and paid access. This goes beyond the schema's own descriptions, though some detail is redundant with the schema.

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

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

The description states a clear verb and resource: it performs grounded multi-source research across Pipeworx's structured data sources, decomposes a question into facets, routes them in parallel, and returns a findings packet. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx. An agent can tell exactly what this tool does and what makes it unique.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also says when NOT to use it: single lookups should use ask_pipeworx, and current-events questions should prefer ask_pipeworx because deep_research relies on the structured catalog. It even provides an authentication-based routing rule: if not signed in, use ask_pipeworx. This is exemplary usage guidance.

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

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

Annotations already declare idempotent and read-only nature. Description adds value by detailing return content (ready-to-call tools with schemas) and noting no second lookup needed.

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

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

Front-loaded with purpose and use case, domain list is efficient. Slightly long but every sentence adds necessary detail.

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?

Even without output schema, description adequately explains what the response looks like and how to use results. All parameters are covered.

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

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

Schema coverage is 100% and all parameters are clearly described in schema. Description hints at limit's role but adds minimal meaning beyond schema.

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

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

Description states specific verb ('Find tools') and resource ('by describing data or task'). Lists extensive example domains (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools by positioning itself as an initial discovery tool.

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

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

Explicitly recommends calling this tool first when exploring many tools ('Call this FIRST...'). Implicitly separates from direct data retrieval tools, though no explicit alternative names provided.

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

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

The description goes far beyond the readOnly/idempotent annotations by explaining cross-source fan-out, the sources_used/sources_failed mechanism, the meaning of empty sections, private-company resolved:false behavior, and the interchangeability of type values. It also notes expected edge cases like small-molecule drugs producing no FDA product results, which is useful and non-obvious.

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 content is highly informative and front-loaded with usage examples, but it is delivered as one long, dense wall of text with heavy parentheticals and semicolon chains. Some details, such as accepted value formats and type interchangeability, are repeated from the schema. Breaking it into structured bullets or shorter paragraphs would improve scanability while keeping the same value.

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

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

With no output schema, the description carries the full burden of explaining return shape, and it does so comprehensively: top-level fields, per-section specifics, source success/failure reporting, and edge-case resolutions. An agent has enough context to invoke the tool correctly and interpret non-obvious outcomes like empty sections or unresolved private companies.

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

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

Even though the input schema already covers both parameters at 100%, the description adds practical meaning: ticker/CIK/name examples, the fact that names resolve via SEC EDGAR, the private-company fallback behavior, and the clarification that 'company' and 'ticker' types are interchangeable. This exceeds what the schema alone communicates.

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

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

The description identifies a specific verb-equivalent activity — producing a full cross-source profile of a US public company — and clearly distinguishes this from single-pack SEC/XBRL/news lookups. The example trigger phrases and the explicit 'ALWAYS PREFER over chaining' make its role unmistakable relative to sibling tools.

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

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

The description states exactly when to use the tool: when the user asks for a holistic view like 'tell me about X', 'research Acme', or 'brief me on Tesla'. It also explicitly discourages chaining single-pack lookups in favor of this one-call approach and explains the accepted input forms, which is strong routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that content is in French and events are sorted by start date, providing useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose, and no wasted words. Efficient and clear.

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

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

For a read-only query tool with full schema coverage and no output schema, the description is sufficiently complete. It explains sorting and language, but does not mention pagination (offset) which is in the schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions filtering by keyword, borough, and date window but does not add meaning beyond what the schema provides. The example boroughs are 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?

The description clearly states the tool finds upcoming public events in Montréal with filtering options. It uses a specific verb ('Find') and resource ('upcoming public events'), and the scope ('Montréal, Canada') distinguishes it from siblings that are unrelated.

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

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

The description implies usage for Montréal events but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No guidance on when not to use it is given.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description confirms deletion but adds only minor context ('the agent saved earlier'). No contradiction, but little added value beyond annotations.

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

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

Two sentences, no fluff, direct and front-loaded with the primary action. Every word serves a purpose.

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

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

Given the simple destructive operation, the description covers purpose, usage, and pairing. No output schema is needed. Annotations provide safety hints. Slightly missing what happens on success/failure, but adequate.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description mentions 'by key' but adds no further meaning beyond the schema. Baseline 3.

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

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

The description clearly states 'Delete a previously stored memory by key.' This is a specific verb-resource pair and distinguishes from siblings by naming remember and recall.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, but does not explicitly state when not to use.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details (fetches page, extracts title/description/links, emits markdown) that go beyond annotations, but does not cover potential issues like rate limits or request failures.

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, beginning with the core purpose, followed by process, then use cases. Every sentence adds value with no redundancy or fluff.

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

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

For a simple tool with two parameters, no output schema, and safety annotations, the description fully covers input, process, output format, and usage scenarios. It is complete without requiring additional explanation.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (url and max_links). The description does not provide additional parameter meaning beyond what the schema already includes, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the verb (generate) and resource (llms.txt file). It distinguishes its purpose from siblings by emphasizing AI crawler indexing, though not explicitly contrasting with similar tools.

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

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

The description lists three concrete use cases (client indexing, own project, competitor audit), providing good context. However, it does not explicitly mention when not to use the tool or name alternative sibling tools for similar tasks.

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, idempotent, openWorld, not destructive. Description adds that it returns specific fields and includes optional parameter for inactive subscriptions, but no further 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?

Two sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words, front-loaded.

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

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

Given simple tool with one optional parameter and complete annotations, description covers purpose, return fields, and usage context adequately without needing output schema.

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

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

Schema coverage is 100% with one parameter described; description does not add additional meaning beyond the schema definition.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb (list) and resource (subscriptions), and distinguishes from siblings like subscribe/unsubscribe.

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

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

Provides explicit when-to-use: 'review what you're monitoring before adding more or to find an id to cancel'. Implicitly guides not to use for subscribing or canceling, but does not name sibling tools explicitly.

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 important behavioral traits beyond the annotations: the claim_token flow and how to use it later, daily rate limit, free/no-quota usage, and that the team reads digests daily. It also warns against pasting end-user prompts. No contradiction with sparse annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then follows with use cases, exclusions, token mechanics, rate limits, and free tier. 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 4 optional params, a nested context object, and no output schema, the description fully covers return behavior (claim_token), usage boundaries, rate limiting, and follow-up call semantics. The only minor gap is not explicitly saying message is required, but schema marks no params required so this is consistent.

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 beyond schema by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and constraining message content ('don't paste the end-user's prompt').

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 pair ('Tell the Pipeworx team something is broken, missing, or needs to exist') and then enumerates concrete trigger types (bug, feature/data_gap, praise). It also distinguishes itself from sibling tools like ask_pipeworx by limiting scope to tools served by this Pipeworx connection.

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 when-to-use guidance is provided (wrong/stale data, missing tool, praise) along with when-not-to-use (another MCP server's tools, with instruction to file there instead). The 'Not sure?' heuristic about Pipeworx tool names gives the agent a clear decision rule.

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

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

Description adds detail beyond annotations: data derived from CF analytics-engine, no PII, cached 5min-1h. Annotations already indicate read-only, idempotent, non-destructive. 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?

Paragraph-style but each sentence adds value (three use cases, caching, no PII). Slightly verbose but no wasted words.

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

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

For a simple 1-param tool with no output schema, description covers return value, data source, caching, use cases. Fully adequate.

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

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

Schema has 1 parameter with enum; description adds semantic guidance on window choice ('hot right now' vs 'steady-state demand'). Coverage 100% gives baseline 3, description elevates it.

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

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

Description clearly states verb 'returns', resource 'top tools, top packs, and total call volume', and scope 'over a recent window'. It uniquely identifies the tool among siblings as a trending data source.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains window selection. Lacks explicit when-not-to-use or alternatives but context is clear.

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

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

The description discloses detailed behavioral traits: monotonicity checks, partition sum checks, Jaccard similarity threshold, placeholder filtering, fill check with CLOB depth, and conditions for null signals. Annotations already declare readOnlyHint=true, idempotentHint=true, and the description adds significant context without contradiction.

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

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

The description is information-dense and front-loaded with the main purpose. However, it is lengthy and includes many details that could be organized more concisely. Still, every sentence serves a purpose for an AI agent.

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

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

Given no output schema, the description details the response structure (opportunities array with gap_pp, suggested_trade, etc.) and explains edge cases (placeholder filtering, fill check). The tool has two optional parameters, and the description covers both modes thoroughly.

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 meaning by explaining the two optional parameters: event (slug or URL) and topic (seed question). Examples and behavior differences are provided, adding 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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between no-args trending scan, event mode, and topic mode, making the resource and verbs specific.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scanning. Examples are provided, and the description explains the benefits of cross-event mode over single-event. Sibling tools like polymarket_edges are not mentioned, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: it explains the three segment types (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with their internal logic, edge calculation details (edge_pp_net, kelly_fraction), tradeable-edge filters, and caching at KV level (1h). It also discloses diagnostic output for empty segments and response structure. 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 very long (over 500 words) and includes extensive technical detail (model formulas, specific parameters, segment logic). While it is well-structured with clear sections and bullet-like phrasing, it could be more concise by condensing less critical details (e.g., specific α values) and focusing on high-level purpose and usage. The front-loading of purpose is effective.

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

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

Given the complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output structure (by_segment with three segments, fed_candidates, _diagnostics), the meaning of each edge metric (edge_pp_net, kelly_fraction, 24h-move warning), and the caching strategy. It fully compensates for the lack of an output schema by describing what the response contains.

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

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

Schema description coverage is 100% (all 9 parameters have descriptions). The tool description adds value beyond the schema by explaining how the 'tradeable-edge knobs' (min_liquidity, max_spread_pp, min_partition_leg_kelly) interact and under what conditions they should be adjusted (e.g., 'Set to 5000 to drop thin-book opportunities'). It provides context that is missing from the per-parameter schema descriptions.

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

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

The description clearly states the tool's verb ('scan') and resource ('top Polymarket markets') and the specific outcome ('return opportunities where Pipeworx data disagrees with market price'). It also articulates the use case ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, relying on implicit differentiation through detailed segment explanations.

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

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

The description implies usage for discovering betting opportunities but provides no explicit guidance on when to use this tool versus alternatives (e.g., polymarket_arbitrage for pure arbitrage or polymarket_fill_risk for execution analysis). It does not include 'when not to use' or direct comparisons to siblings. The detailed knob explanations offer context but not selection criteria.

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

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

The description adds extensive behavioral details beyond the readOnlyHint and idempotentHint annotations: it explains the response structure (tracked, expired, snapshot_dates), how decay numbers are computed (daily closes, not intraday), and limits (snapshot TTL). No contradictions.

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

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

The description is detailed but well-structured with clear sections for response fields and limits. It is slightly long but each sentence adds value, so it 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?

Despite no output schema, the description comprehensively explains the return format (tracked, expired, snapshot_dates with detailed fields) and limitations. It is fully complete for a complex tool with two parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds default values and clarifies that 'window' refers to snapshot family, but does not add significant new meaning beyond what the schema already provides.

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

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

The description clearly states the tool tracks edge persistence and decay telemetry, answering when an edge has existed and whether it's shrinking. It explicitly differentiates from the sibling polymarket_edges by being built from its daily snapshots for time-series analysis.

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

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

The description provides clear context for use (comparing fresh vs old wide edges) and mentions limitations (60-day TTL, daily closes). However, it does not explicitly contrast with alternatives like polymarket_edges, though the differentiation is implicit.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: walks the ladder, returns specific fields, warns about partial basket fills causing unhedged directional risk. No contradiction with annotations.

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

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

The description is detailed (250+ words) but well-structured with clear sections for each mode. Could be slightly more concise, but every sentence adds value.

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

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

Given the tool's complexity, the description covers purpose, usage, parameters, return values, and behavioral warnings. Even without an output schema, return fields are described. 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% with descriptions. The description adds meaning: explains mode selection (market vs event), auto-detection for basket side, and interpretation of size_usd for basket (settlement notional). Adds value beyond schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket), which differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial fills convert arb to directional position). Also specifies required parameters for each mode.

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

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

The description goes far beyond the annotations: it discloses the pairing-unverified nature of matches, the gross-not-net fee treatment, null temporal_alignment semantics, skipped leg counters, and response safety fields. It reads strictly consistent with readOnlyHint=true and idempotentHint=true.

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 organized into identifiable sections (modes, response, safety fields, fee note, skip counters), and the most critical warning is placed at the end. It is longer than ideal and slightly repeats the temporal_alignment_unknown/null distinction, but nearly every sentence contributes unique 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?

Absent an output schema, the description covers the return shape (leg-by-leg prices, top_spreads_pp, skipped_unclassified, low_confidence_pairs), the meaning of compatibility flags, fee treatment, and temporal alignment edge cases. Nothing essential for invoking the tool correctly appears to be missing.

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

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

Even with 100% schema coverage, the description enriches the parameters: it enumerates all ten topic shortcuts, gives concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825', and states that explicit values override the topic-mapped side and that both modes run the same matcher.

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

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

The description opens with a concrete resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' and immediately details two modes and the response contents. It does not explicitly contrast itself with a sibling like polymarket_arbitrage, which would have made the distinction even stronger.

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 explains mode selection clearly: use the pre-mapped topic shortcuts or supply explicit kalshi_event_ticker and polymarket_event_slug for custom pairings, and warns that pre-mapped topics often carry compatibility warnings. However, it never names an alternative tool or an explicit when-not-to-use case, leaving the comparison vs siblings implied.

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

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

Annotations already mark readOnly=true and idempotent=true; description adds helpful context about scoping to user identifier and the pairing with remember/forget. 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?

Four sentences, front-loaded with the key action, each sentence adding a distinct piece of information (usage, scope, related tools). No fluff.

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

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

Given a single optional parameter, no output schema, and rich annotations, the description fully covers the tool's behavior, scope, and relationship to siblings.

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 already describes the 'key' parameter well. Description reinforces the omission behavior (list all keys) and adds context about the parameter's role, exceeding the baseline.

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

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

Description starts with a clear verb+resource pair ('Retrieve a value') and distinguishes from sibling tools 'remember' and 'forget' by explicitly stating the association. It also covers the alternate usage of listing all keys.

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?

Describes use case for looking up previously stored context without re-deriving, and scoping to identifier. Does not explicitly mention when not to use, but the context is clear given the three-memory-tool set.

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

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

The description discloses that setting mark_read:true flags events as read, which modifies server state. This directly contradicts the annotation readOnlyHint=true, which asserts no state modification. Per the scoring rules, this contradiction results in a score of 1.

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

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

The description is concise at 3-4 sentences, front-loads the purpose, and every sentence provides useful information. No unnecessary words.

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

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

Covers returned fields, filtering, and polling, but omits explanation of pagination (limit) and unread_only behavior. Given the 5 optional parameters and no output schema, the description is moderately complete but has gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context for type, since, and mark_read parameters, but does not cover limit or unread_only beyond what the schema already provides. This adds marginal 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 it pulls fired events from the subscription feed and lists the data fields returned. However, it does not differentiate itself from sibling tools like 'events', leaving the agent to infer which to use for subscribed alerts vs. general events.

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 guidance on filtering by type and since, and explains mark_read behavior for polling. Mentions an alternative REST endpoint for scripts/dashboards. Does not explicitly state when not to use this tool or compare to siblings like 'subscribe' or 'list_subscriptions'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantial context: it fans out to multiple sources (SEC EDGAR, GDELT/GNews fallback, USPTO), notes API sunset and soft-fail behavior, and describes the return format. 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 a single paragraph but is dense with useful information. It front-loads example queries and uses clear language. While slightly compact, every sentence contributes meaning. Could be slightly more structured (e.g., bullet points) but remains highly efficient.

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

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

There is no output schema, but the description outlines return fields ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), which is sufficient. All aspects of the tool—parameters, behavior, fallbacks, and exclusions—are covered. The tool's simplicity and rich annotations make this 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% with descriptions for all three required parameters. The description adds value by explaining the `since` parameter's accepted formats (ISO date or relative shorthand) with an example usage hint ('Use "30d" or "1m" for typical monitoring'), and clarifies that `value` accepts ticker or CIK. This goes 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 returns a change feed for a company over a recent time window, with example queries like 'What's new with X'. It explicitly distinguishes from sibling tool 'entity_profile' by specifying when to use the alternative. The verb 'return' and resource 'change feed' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool (e.g., 'What's new with X', 'latest on Y') and when not to ('Use entity_profile instead when you want the static profile...'). It also explains fallback behavior between GDELT and GNews, giving clear context for invocation.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description elaborates on scoping (by identifier) and persistence (authenticated vs anonymous sessions with 24-hour expiration). No contradictions. Adds value beyond annotations by explaining data lifecycle.

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 purpose, followed by usage guidance, examples, and behavioral details. Every sentence contributes essential information. Slightly verbose due to enumeration of examples, but overall concise.

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

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

For a simple write tool with no output schema, the description covers the key aspects: purpose, usage triggers, data scope, persistence, and companion tools. It does not describe return values or error handling, but those are less critical for a write operation.

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

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

Schema coverage is 100% with concise descriptions for 'key' and 'value'. The description provides naming conventions (e.g., 'subject_property', 'target_ticker') that add practical guidance beyond the schema. Since coverage is high, the extra examples lift the score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the action (save), resource (data), and context (across conversation or sessions). The examples and pairing with siblings distinguish it from 'recall' and 'forget'.

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

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

The description explicitly advises when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also mentions pairing with 'recall' and 'forget' for lifecycle management. However, it does not explicitly state when not to use, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description's job is to add behavioral context beyond safety. It does this extensively: it explains identifier source labeling, explicit `unresolved` reporting, `figi_candidates` on ambiguity, graceful degradation when LEI/FIGI enrichment fails, multi-endpoint cascading, and special ISIN-to-LEI resolution. Nothing contradicts the annotations.

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

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

The description is front-loaded with examples and the key usage rule, but it is an extremely long single block of dense parenthetical prose. Much of the detail is valuable, but it would be easier for an agent to parse if separated into scannable sections for company behavior, drug behavior, ambiguity handling, and degradation. It is more dense than concise.

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

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

There is no output schema, so the description carries the burden of explaining what the tool returns. It covers return types (CIK, ticker, company_name, LEI, FIGI, RxCUI), source provenance, unresolved identifier handling, ambiguous-match behavior, and failure degradation. For a two-parameter lookup tool with rich edge cases, this is as complete as an agent needs.

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 and the schema already documents `type` and `value` with examples. The description adds valuable operational semantics beyond the schema: the instruction to pass the entity name only, the warning about trailing security-class words for bonds, the accepted input forms, and the meaning of the supported enums. This justifies one point 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 names a specific verb and resource: resolving a user-spoken name to canonical/official identifiers needed by other tools. It distinguishes the tool from siblings like entity_profile and compare_entities by framing it as the identity-lookup layer, and it enumerates supported entity types and identifier sources. The "Use FIRST" instruction further sharpens the purpose.

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

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

It explicitly says "Use FIRST whenever you have a name but need an ID," which gives clear invocation context. It also explains behavior on ambiguous matches and non-resolvable identifiers, but it does not name alternative tools or state when not to use it, so it falls just short of a full when/when-not/alternatives treatment.

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

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

Annotations already provide readOnly, idempotent, openWorld hints. Description adds that it internally calls ai_visibility_check per entity and requires an API key for Anthropic models, providing useful behavioral context beyond annotations.

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

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

Three sentences efficiently convey purpose, usage, and output structure. No redundancy, front-loaded with key action.

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 output schema, description explicitly names return fields (score, confidence, signal density). Explains internal delegation to ai_visibility_check. Sufficient for agent to understand behavior and output.

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

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

Schema coverage is 100% but description adds key semantics: 'First entry treated as the subject for narrative; rest are competitors.' This goes beyond schema descriptions and clarifies how entities are interpreted.

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, probes each with ai_visibility_check, ranks results, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity).

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 for competitive AI-marketing audits' and gives an example question. Implicitly contrasts with ai_visibility_check for single entities, but no explicit when-not-to-use statement.

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

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

Discloses important behavioral details beyond annotations: first bundlephobia measurement takes 5-30s, partial failures degrade gracefully, and sources_failed lists timeouts. 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 thorough but not overly verbose. It front-loads the core purpose and uses bullet-like structure for return values. Could be slightly tightened, but each sentence adds value.

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

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

Given the tool's complexity (multiple sources, timing, partial failures), the description covers all necessary context: output fields, behavior on failure, ecosystem scope, and version handling. No output schema exists, so the explanation of return values is 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?

Parameter schema coverage is 100%, so the description adds little beyond what is already documented. It repeats acceptance of scoped packages and default version, which are in the schema. No additional semantics.

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

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

The description clearly states it is a composite check for npm packages using deps.dev and bundlephobia, specifying the exact purpose and distinguishing it from sibling tools via ecosystem and composite nature.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also gives exclusion: NPM only in v1, with alternatives for other ecosystems.

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

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

Description discloses embedding model (BGE-base-en), chunking (500-char overlapping windows), similarity measure (cosine), character cap (200K), and truncation behavior. This adds significant context beyond annotations which already indicate read-only, idempotent, etc.

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

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

Well-structured single paragraph with clear front-loading of purpose. Every sentence adds value, though could be slightly more concise without losing 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?

Completely covers all aspects: what it does, when to use, how it works (embeddings, chunking, scoring), limitations (200K cap, truncation), and return value (passages with offsets). No output schema, but description adequately explains return format.

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 meaningful examples for 'query' and clarifies the 'text' parameter's purpose and limit. The 'limit' parameter's range is also noted, adding 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 it performs semantic search inside a fetched record, gives concrete examples (SEC 10-K, article), and distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt, explains how it saves context, and provides an alternative usage pattern (fetch with gateway, ground over passages).

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

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

Beyond annotations (idempotentHint, destructiveHint, readOnlyHint), the description adds behavioral context: returns a new subscription ID, requires a specific account type, details on delivery channel limits (SMS 10/day), webhook signing and auto-disable after 10 consecutive failures, and that a feed is always available.

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 purpose and requirements, then systematically lists types and delivery options. While fairly long, every sentence adds value; it could be slightly more concise but remains readable and well-structured.

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

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

Given no output schema, the description explains the return value (subscription ID). It covers prerequisites, supported types with parameter formats, delivery channels with constraints, and the always-on feed. It is fully complete for a subscription creation 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?

With 100% schema coverage, the baseline is 3, but the description adds substantial value: for each subscription type, it provides concrete examples in the 'params' description and explains delivery channels with constraints (phone verification, SMS cap, webhook secret). This goes well beyond the schema's minimal descriptions.

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

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

The description uses a clear verb 'create' and identifies the resource as a 'proactive monitoring subscription to a live-data event stream'. It distinguishes from sibling tools like 'list_subscriptions' and 'recent_alerts' by focusing on creation of subscriptions.

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

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

The description provides clear context: requires a Pipeworx OAuth account, lists supported subscription types with detailed parameter examples, and explains delivery channels. It does not explicitly state when not to use or alternatives, but the context is sufficiently clear for an agent to decide.

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, destructiveHint=false. The description adds that it returns example questions with tool/argument shapes and can be called with no args or a topic. This adds value beyond annotations, but no critical behavioral details are missing.

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 somewhat long but front-loaded with common queries. It organizes topics in a parenthetical list. Could be slightly tighter, but each sentence adds value.

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

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

For a simple tool with 1 optional parameter and no output schema, the description fully covers purpose, usage, parameter behavior, and when to use. No gaps.

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

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

Schema coverage is 100%. The description adds examples of topic values ('finance', 'pharma', etc.) and explains that omitting topic gives a cross-category spread, which adds meaning beyond the schema's 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 it returns category-bucketed example questions and is the onboarding entry point. It uses specific verbs ('returns', 'use this FIRST') and distinguishes from siblings by explaining it's for when the agent doesn't know what Pipeworx can do.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Does not explicitly state when not to use, but context is clear.

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

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

The description explains that the row is 'deactivated (not deleted)' and historical events remain available via recent_alerts, adding context beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). No contradictions.

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

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

Two sentences with no wasted words. The first sentence states the action, the second provides key behavioral details. Front-loaded 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?

For a single-parameter tool with no output schema and good annotations, the description fully covers what the agent needs: action, ownership, effect on data, and tie to related tool recent_alerts.

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 the single 'id' parameter. The description adds 'by id' but the schema already defines the param as 'Subscription id (uuid) returned by subscribe.' 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 'Cancel a subscription by id' (specific verb+resource) and distinguishes from siblings like subscribe and list_subscriptions by noting ownership enforcement and deactivation behavior.

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

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

It explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear guidance on when to use the tool and when not. No alternative tool is named, but the context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral nuance beyond this: the dual verification paths (SEC EDGAR/XBRL vs. grounded pipeline), the meaning of each verdict, and especially the important distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source covers it). This is exactly the kind of context annotations cannot capture.

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 every sentence carries substance: examples, core purpose, routing logic, verdict semantics, and the crucial caller warning. It is well-structured with a clear flow. It could be slightly tighter without losing value, but it earns a 4 for being information-dense rather than padded.

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

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

Despite having no output schema, the description fully describes return values (verdict, actual value with citation, reasoning) and explains edge cases ('could_not_verify' vs 'unsupported'). It also covers the tool's composite nature (replacing 4–6 sequential calls). For a 2-parameter tool with no output schema, 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% with good descriptions for both 'claim' and 'tolerance_pct'. The description adds value beyond the schema by advising to set tolerance_pct to 1–2 for hallucination detection and explaining the default is implied by wording, capped at 5. This practical guidance helps the agent choose parameter values correctly.

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

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

The description uses a specific verb ('validate', 'check', 'verify') with a clear resource ('natural-language factual claims against authoritative sources'). It explicitly distinguishes itself from alternatives by describing the fallback pipeline and noting it 'Replaces 4–6 sequential calls'. The inclusion of example query phrasings 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 states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two distinct paths (company-financial vs. any other factual claim) and instructs callers on interpreting verdict values. However, it does not explicitly name sibling tools to avoid or contrast with, so it falls short of a 5 on explicit 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.