Data Batonrouge

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds valuable details: scoring 0-100 per model, default model choice, API key handling (BYO key, direct payment), and return format (score, confidence, signals, raw_response, combined view). 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?

Three sentences: first states main action and output, second details default model and key requirement, third lists use cases. No filler, front-loaded, 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?

With no output schema, the description sufficiently explains return format. Parameters are fully documented in schema. Use cases are given. Annotations provide safety profile. Agent has enough to decide invocation and parameter setup.

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 clear parameter descriptions. Description adds value beyond schema by explaining default behavior (free Workers AI model), how _apiKey is used (passed to Anthropic directly), and that context helps disambiguate. Baseline 3, plus extra semantic context.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the specific topic 'what they know about a business/brand/product/topic' with a visibility score. It distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on AI visibility audits.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it doesn't say when not to use, the context is clear and no alternatives are given. The cost implication for Anthropic is noted.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context about routing to internal tools, filling arguments, and returning stable pipeworx:// citation URIs. It does not mention failure modes or rate limits, but this is not required given the strong annotation coverage.

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

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

The description is front-loaded with the main instruction and contains useful specifics, but it is lengthy due to multiple overlapping lists of domains, trigger phrases, and examples. The apparent duplicate 'START HERE for most questions' trailing passage adds redundancy. Overall it is acceptable but not tightly edited.

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 a single required parameter, no output schema, and rich annotations, the description covers behavior, scope, usage guidance, and return format. It explains that the answer is structured and includes stable citation URIs. It lacks explicit fallback or limitation guidance, but the tool's simplicity and annotation coverage make the description substantially complete.

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

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

The input schema already documents the question parameter and its aliases with 100% coverage. The description supplements this by providing example queries and the kinds of phrasing expected, which helps an agent formulate the argument correctly. The examples add practical meaning beyond the schema's simple 'natural language' 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 identifies the tool as a natural-language router that sends questions to the right one of 5,798 tools and returns a structured answer with citations. It states the resource and scope explicitly with domain examples. It does not differentiate from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it misses full sibling distinction.

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 prefer this over web search for factual, current, or historical questions, and lists trigger phrases and concrete examples such as 'current US unemployment rate'. It also says 'START HERE for most questions.' It does not discuss when to choose sibling research or query tools, but the primary alternative (web search) is clearly directed.

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

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

Beyond the read-only and idempotent annotations, the description discloses meaningful operational behavior: candidate routing improvements are enabled live during tests, no candidate is currently active, and the beta currently matches the stable router exactly. It also clarifies that it does not fall back to another tool — it is a fully working router.

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

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

The description is longer than average but each sentence adds useful context: variant identity, current experimental status, usage instruction, and reassurance that it is a complete router. The date-specific retirement detail is slightly noisy but not wasteful.

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 still tells the agent everything needed to invoke it: same arguments as ask_pipeworx, same response shape, current live behavior, and how to use it. The tool's complexity is well covered.

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

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

Schema description coverage is 100%, and every parameter is already documented as an alias for 'question'. The description adds no new semantic meaning about parameters beyond saying the tool takes 'same arguments' as ask_pipeworx, so the schema carries the load.

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

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

The description states clearly that this is a beta variant of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It differentiates itself from the stable sibling by emphasizing its experimental role, so an agent can tell it apart from ask_pipeworx and 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?

It gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges. However, it does not explicitly state when NOT to use it, such as preferring the stable router for production-sensitive calls.

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 non-obvious behaviors beyond the annotations: it will not invent facts, returns explicit refusal reasons, uses only tool-result content, and requires an extra LLM call. These details add real value on top of the readOnly/openWorld/idempotent hints. 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?

Though detailed, every sentence earns its place: mode, process, success response shape, refusal contract, usage criteria, and cost tradeoff. The core purpose is front-loaded, and there is no filler.

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

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

With no output schema, the description compensates thoroughly by specifying exact success fields and every refusal_reason enum value. It also covers the key decision factor (high-stakes vs. casual lookups) and the extra-call tradeoff, leaving nothing essential for an agent to guess.

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 question parameter and all aliases are already described. The description adds no parameter-specific semantics beyond the tool's routing behavior, which is appropriate because the schema carries the parameter meaning.

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, distinct capability: 'hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from the sibling ask_pipeworx by explaining it extracts answers only from tool results, returns evidence/refusals, and costs an extra LLM call.

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 ('whenever an answer will be quoted, cited, or acted on') with concrete high-stakes examples, and when not to ('prefer ask_pipeworx for casual lookups'). This directly guides routing among siblings.

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 fully discloses behavioral traits: resolution mechanism, fan-out logic, response shapes, safety short-circuits (low-confidence, closed markets), edge-case handling (wide spreads, cancellation rules), and grounding evidence fields. This far exceeds the annotations' readOnlyHint and idempotentHint, providing rich context for agent decision-making.

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

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

The description is lengthy but justified by the tool's complexity. It front-loads the core purpose and then systematically details categories, examples, and edge cases. While every sentence earns its place, it could be slightly more concise by grouping related concepts.

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 covers input handling, resolution confidence, parent events, news fallback, market statuses, and cancellation rules. It leaves no significant gap for an agent to misuse the tool, making it fully contextual for the given complexity.

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

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

The input schema has 100% coverage, and the description adds significant value by explaining the 'depth' enumeration (quick vs thorough), 'include_raw' behavior (default false, payload size trade-offs), and examples for 'market'. This goes beyond the schema's minimal descriptions, making parameter semantics exceptionally clear.

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 researches a Polymarket bet, specifying input types (slug, URL, question text) and output (evidence packet + comparison). It is specific and action-oriented, but does not explicitly distinguish itself from siblings like 'polymarket_edges' or 'polymarket_arbitrage', which slightly reduces the score.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and lists classifiers and fan-out examples. However, it does not mention when to avoid using the tool or alternatives, so it stops short of a 5.

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

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

Describes handling of off-calendar fiscal years and sorting by primary metric, adding context beyond annotations which already mark it as read-only, idempotent, and non-destructive.

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

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

Concise yet comprehensive, front-loading purpose and trigger phrases, with every sentence adding value and 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?

Covers all aspects needed for use: input types, data sources, result ordering, and output format (paired data + citation URIs), despite no 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?

Adds significant meaning beyond the input schema by explaining the 'type' enum and 'values' array with examples, usage constraints, and what data is pulled for each type.

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

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

Clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, provides trigger phrases, and distinguishes from 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 says 'ALWAYS PREFER over sequential single-pack lookups' and states it replaces 8–15 sequential lookups, guiding when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and behavior. The description adds value by specifying the returned fields and the expected workflow, but does not elaborate on authorization or rate limits.

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

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

The description is concise, two sentences long, with the action and resource front-loaded. Every sentence serves a purpose: defining the search and explaining the output. 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?

Given the rich annotations, fully documented input schema, and lack of output schema, the description provides complete context: it explains the tool's purpose, return value, and next step, leaving no critical gaps for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new details about parameters beyond what the schema already provides, but it correctly implies the role of 'query' as the keyword.

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

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

The description clearly states the action 'search', the resource 'open datasets', the source 'Baton Rouge Open Data catalog', and the specific output fields. It distinguishes itself by specifying the catalog's geographic scope, which is unique among siblings.

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

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

The description implies usage when searching for datasets by keyword and hints at a follow-up action (pass resource_id to query/metadata), but it does not explicitly state when to use this tool versus alternatives or provide exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: an account is required, thorough depth needs a paid plan, the call takes 15-90s, gaps[] are never invented, citations are only included when fetchable, contradictions[] appear for standard/thorough, and large records are semantically excerpted. This fully informs the agent about side effects, prerequisites, and output reliability.

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

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

The description is long but every sentence carries either prerequisites, scope, method, output structure, or timing. Critical information (account requirement and the alternative tool) is front-loaded. The heavy use of semicolons and nested clauses makes it dense, but the logical flow is coherent and nothing is 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?

With no output schema, the description must explain return values, and it does thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also explains auth requirements, depth costs, latency, and excerpting behavior. For a tool of this complexity, this is complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful enrichment by explaining depth tiers beyond the enum descriptions: quick=3 facets single-hop, standard=3 with gap recovery and contradictions, thorough=6 paid with iterative lead-chasing. It also reaffirms that the question parameter accepts natural-language multi-part questions. This extra semantic context earns a 4.

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

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

The description opens with a specific, named capability: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It clearly states the tool decomposes questions into facets, routes them in parallel across 5,798 tools, and returns a findings packet. It also distinguishes itself from open-web search and from sibling ask_pipeworx, making its unique role 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 gives explicit routing guidance: if not signed in, use ask_pipeworx; for a single lookup, use ask_pipeworx; for broad/multi-part questions over structured data, use deep_research. This is a model example of when-to-use versus when-not-to-use guidance with named alternatives.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description carries less burden. It adds value by explaining that results include full input schemas with examples and that tools are ready to call directly, which informs the agent about the behavior beyond the annotations. 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 a single paragraph that front-loads the purpose and then details usage, return format, and call order. It is concise but includes a lengthy list of domains; while informative, this could be slightly trimmed. Overall well-structured and no excessive verbosity.

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 compensates by stating the return format (top-N tools with names, descriptions, and full schemas with examples). It covers the tool's purpose, usage guidance, and behavioral aspects. It does not mention error handling or rate limits, but given the read-only/idempotent nature, this is acceptable. Complete for the tool's complexity.

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

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

Schema description coverage is 100% (baseline 3). The description adds example values and lists aliases for the query parameter, which is helpful but does not significantly supplement the schema. Since the schema already thoroughly documents each parameter, the description offers marginal added 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 uses a specific verb ('Find') and resource ('tools') and explicitly distinguishes this tool from siblings by stating it is for browsing/discovering available tools, not for executing specific queries. It also provides a list of example domains, clarifying the scope.

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

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

The description clearly states when to use ('Use when you need to browse, search, look up, or discover what tools exist for...') and gives explicit guidance to call this FIRST when having many tools. It implicitly tells when not to use (when you already know the tool) and provides context about returning ready-to-call results, aiding selection among siblings.

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

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

With annotations already marking this as read-only, idempotent, and non-destructive, the description still adds substantial behavioral context: it fans out across many named sources, soft-fails on USPTO patents, returns empty sections as genuine 'no data' versus bugs, and exposes `sources_used`/`sources_failed`. It even explains the FDA/biology-narrow scope and the GDELT→GNews fallback, going far beyond the annotations.

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

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

The description is long, but it is dense and structured: examples first, then the core directive, then a clearly enumerated return layout, then input rules and edge cases. There is minor redundancy with the schema ('type accepts company or ticker interchangeably'), and the wall of semicolon-heavy clauses is hard to scan, but nearly every sentence earns its place given the tool's complexity.

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

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

For a high-complexity tool with no output schema, this is unusually complete. It documents all accepted input shapes, enumerates each returned section with example URIs and source caveats, explains expected empty results (FDA biologics, private companies), and covers failure modes via `sources_failed`. An agent has enough context to decide when to call it and how to interpret its result without additional discovery.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the zero-padded CIK convention, that names resolve via SEC EDGAR's company-name match, that `type` values are interchangeable in practice, and that private companies resolve to `resolved:false` with an explicit note. This is meaningful contextual enrichment, though the schema already carries much of the parameter 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 opens with concrete natural-language triggers and a crisp statement of what the tool does: 'full cross-source profile of a US public company in ONE parallel call.' The verb is specific ('profile' / 'fan out across sources') and the resource is bounded ('US public company'), which differentiates it from sibling tools like resolve_entity (single resolution) and compare_entities (comparison rather than profile).

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies input flexibility (ticker, CIK, or name), the acceptable `type` values, and how private companies are handled with `resolved:false` and a `notes` line rather than a failure.

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 the description confirms destructive action (delete). While it adds the 'by key' specificity, it does not disclose additional behavioral details like irreversibility or side effects.

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?

Extremely concise: one sentence for purpose, one for usage, one for pairing. Front-loaded with no wasted words.

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

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

Given the simple one-parameter tool with no output schema, the description covers purpose, usage, and pairing adequately. 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%, and the description does not add meaning beyond the schema for the single parameter 'key'. Baseline score of 3 applies.

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

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

The description clearly states the verb (Delete) and resource (memory by key), distinguishing it from sibling tools 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?

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and suggests pairing with remember and recall, offering strong 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it fetches the page, extracts content, and emits standard markdown, providing context beyond annotations. No contradictions.

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

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

Three sentences, front-loaded with the main action, and no wasted words. Every sentence serves a purpose: defining the tool, its behavior, and its use cases.

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

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

Despite no output schema, the description fully explains the output (single text blob, ready to drop at site-root/llms.txt). Combined with annotations and schema, it covers purpose, behavior, parameters, and output format completely for this non-complex tool.

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

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

Schema description coverage is 100%, and the description does not add significant information beyond what the schema provides. For the 'url' parameter, description adds example format; for 'max_links', it already includes default and max in schema. 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 it generates an llms.txt file for a given URL, specifying what it extracts (title, description, key links) and the output format. It distinguishes itself from sibling tools by focusing on this specific task, which none of the siblings appear to duplicate.

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 three use cases: getting a client's site indexed, drafting for your own project, or auditing competitor indexing. It does not explicitly mention when not to use or provide alternatives, but the context is clear enough for an AI 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 indicate read-only, idempotent, non-destructive behavior. Description adds return field details but no new behavioral context.

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

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

Two concise sentences: first covers purpose and output, second provides usage context. 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?

Simple read tool with one optional param and no output schema; description lists return fields. Annotations cover safety. Adequate for agent use.

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

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

Schema covers 100% of parameters with description for include_inactive. Description adds no additional 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?

Clearly states 'List the caller's active subscriptions' and enumerates returned fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises use for reviewing subscriptions before adding or canceling. No when-not stated, but context with sibling tools suffices.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value beyond annotations by specifying what data is returned (columns, types, row count, category, last-updated). This informs the agent about the response content without needing an output schema.

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 a single, front-loaded sentence that efficiently conveys the tool's purpose, scope, and an example. No redundant or unnecessary words.

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

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

Despite no output schema, the description lists the return fields reasonably well (columns, types, row count, category, last-updated). It is nearly complete for the given tool complexity, though it could optionally mention the format or if all columns are returned.

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 the parameter description already stating 'Dataset id, e.g. "fabb-cnnu".' The description does not add new semantic information beyond what the schema provides; it only restates the example. Baseline score of 3 is appropriate.

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

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

Description clearly states the action (Get), the resource (dataset's schema + metadata), and lists specific fields (columns, types, row count, category, last-updated). The example resource_id further clarifies usage. This distinguishes it from siblings like 'datasets' which likely list datasets rather than a single dataset's schema.

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

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

The description implies usage for retrieving schema/metadata of a specific dataset, but does not explicitly mention when to use this tool versus alternatives (e.g., 'datasets' or other query tools). No exclusions or contextual guidance is provided.

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

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

Annotations already declare non-read-only and non-idempotent behavior, but the description adds key operational details: rate limiting ('Rate-limited to 5 per identifier per day'), no quota cost ('Free; doesn't count against your tool-call quota'), and the claim_token follow-up mechanism ('Filing without an account returns a claim_token... to read whether it was fixed'). It also clarifies that the team reads digests daily, providing insight into what happens after submission.

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

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

The description is long but front-loaded with purpose, followed by usage conditions and mechanics. Every sentence carries distinct information (scope, types, caveats, token flow, roadmap impact, rate limits), with no filler or repetition.

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

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

Given that the tool has no output schema and requires nuanced procedural knowledge, the description is fully self-contained: it covers eligibility, content expectations, follow-up, rate limits, and how to distinguish Pipeworx tools from others. Nothing essential is left unexplained.

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

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

The schema already covers all parameters (100% coverage), but the description adds semantic value for claim_token by explaining the round-trip workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and for message by advising 'Be specific (which tool, what error, what data was missing)'. This goes beyond the bare parameter names.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's verb and resource. It further distinguishes the tool by enumerating feedback types (bug, feature/data_gap, praise) and explicitly scoping it to 'tools served by this Pipeworx connection', unlike siblings like ask_pipeworx or query.

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

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

The description specifies exactly when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also instructs how to phrase feedback and how to use claim_token, giving clear operational 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?

Adds valuable context beyond annotations: data source (CF analytics), privacy (no PII), caching behavior (5min-1h), and aggregation method. 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?

Concise three-sentence structure: purpose, use cases, technical details. Every sentence adds value with no redundancy.

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

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

Complete for a simple tool with one parameter and no output schema: covers purpose, usage, behavior, and parameter guidance adequately.

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?

Adds contextual meaning to the window parameter beyond the enum values, explaining how different window lengths surface different trends.

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

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

Clearly states the tool returns top tools, packs, and call volume over recent windows, distinguishing it from siblings like discover_tools or datasets.

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 three explicit use cases for when to use the tool, but does not explicitly state when not to use or suggest alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: scan modes, Jaccard similarity filter for semantic anchor, placeholder fraction filter, fill check against live CLOB depth, and tradeability conditions. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with purpose. Each paragraph serves a clear function (general scan, event mode, topic mode, semantic anchor, partition filter, response format, fill check). Could be slightly more concise, but no wasted sentences.

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

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

With no output schema, the description fully explains the response format and edge cases (fill check, placeholder filter, similarity threshold). Covers all necessary information for correct usage, including tradeability conditions.

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 both parameters described. The tool description adds extra meaning: acceptable input formats (e.g., full URLs for event), recommendation for mode selection, and detailed behavior for each parameter. Adds significant 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 the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and is specific about the resource and actions, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 no args (trending_scan), event mode (recommended for a specific market), and topic mode (for cross-event scanning). Provides guidance on not trading when realizable_edge_pp ≤ 0, and recommends custom sizing via polymarket_fill_risk. Clear context and exclusions.

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

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

The description extensively details behavior beyond annotations, covering three model families, edge computation, slippage, Kelly fractions, tradeable-edge knobs, response structure with diagnostics, and caching. 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 thorough but lengthy, with dense technical details that may overwhelm. While every sentence adds value, the length impacts conciseness; a more streamlined structure could improve readability.

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 (9 parameters, no output schema), the description covers expected output structure (by_segment, diagnostics), explains empty segments, and details edge calculation, making it complete for effective tool usage.

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

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

Schema coverage is 100%, and the description adds meaning by explaining concepts like 'NET of slippage', 'half-Kelly fraction', and 'tradeable-edge filters' with practical usage notes, enhancing understanding beyond basic parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource and action, and distinguishes from siblings by naming use cases and model families.

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 for use: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It explains constraints like Fed bets being excluded and cache behavior, but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations declare read-only and idempotent. Description adds behavior: returns time-series, trend classification, decay rate, lifespan; explains snapshot writing on cache-miss causing gaps. 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?

Front-loaded with core question and answer. Structured into response format breakdown and limitations. Every sentence adds value; slightly lengthy but justified by complexity.

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

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

Thoroughly explains output structure (tracked, expired, snapshot_dates) with field meanings and limitations. No output schema, so description carries full burden; well-covered for a time-series analysis 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%, but description adds context: default values, clamp range for days, and how window family relates to snapshots. Also explains how parameters affect output (e.g., days determines lookback). Provides extra clarity beyond bare schema.

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

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

Clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' Distinguishes from raw edge data by tracking time-series. Specific verb 'answers' and resource 'edge persistence'.

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?

Implies usage for assessing edge freshness vs staleness, contrasting fresh wide edges with old wide edges. Mentions limitations like 60-day TTL and snapshot gaps. Lacks explicit 'use this when' or comparison to siblings like polymarket_edges, but context is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by explaining the live order-book check, ladder walking, and return fields like 'verdict' and 'forced_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 somewhat long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET) and capital emphasis. Every sentence provides necessary detail for a complex tool, though slight verbosity prevents a perfect score.

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

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

Despite no output schema, the description enumerates all key return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers edge cases like thin_legs and forced_directional_risk. With annotations present, this provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains size_usd differently for single-market vs basket, default side logic for basket (auto from partition sum), and the required mutual exclusivity of market/event. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with explicit modes (single-market and basket). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by specifying when to use it, using a specific verb+resource combination.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about partial fills converting an arb into an unhedged directional position, giving clear context for when not to skip this tool.

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

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

Annotations already mark this as read-only and idempotent, but the description adds substantial behavioral detail: spread_pp is gross and not net of Kalshi fees, compatibility codes can be non-empty even when matched_pairs>0, unknown legs are never paired, and temporal_alignment null means 'could not be computed' rather than 'aligned'. No contradiction with the annotations.

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

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

The description is long, but it is front-loaded with the core purpose and organized with clear uppercase labels for modes, response shape, safety fields, and fee treatment. Each block carries non-obvious operational caveats that matter for correct invocation and interpretation. It could be tightened in places, but the length is largely justified by 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?

Given no output schema and a complex result shape, the description thoroughly documents response fields, compatibility codes, per-entry flags, skipped-leg counters, and fee semantics. One small gap: with 0 required parameters, it does not state what happens when neither `topic` nor explicit pairing parameters are provided.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description adds mode-level semantics beyond the schema: `topic` auto-fetches matching events on each venue, explicit parameters override the topic-mapped side, and both modes run the identical token-overlap matcher. This is meaningful context that the individual schema descriptions do not provide.

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 opening sentence names a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further clarifies the output sign as 'Kalshi − Polymarket' and describes two modes, so an agent can distinguish this from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description clearly explains when to use each mode: pre-mapped `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning today. It does not explicitly name alternatives for when to prefer this tool over a sibling, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds 'Returns matching rows as JSON', which is useful but minimal 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 example, 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?

Given 7 parameters, full schema coverage, and rich annotations, description explains query language and return format. Could mention default limit of 1000, but otherwise 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%. Description adds crucial context: SoQL clauses should be used without leading $, and explains limit/offset. Adds 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 'Run a Socrata SoQL query', resource 'Baton Rouge Open Data dataset by resource_id', and provides an example. Distinguishes from sibling tools like 'datasets' and 'metadata'.

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?

Explains how to filter with SoQL clauses and pagination parameters. Does not explicitly state 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds useful context: scoped by identifier (anonymous IP, BYO key hash, account ID) and lifecycle pairing with remember/forget. 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?

Three sentences, front-loaded with action and scope. Every sentence adds value: purpose, usage examples, scope and pairing. No wasted words.

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

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

The description explains how to use the tool but does not specify the return format (what the retrieved value looks like). Given no output schema, this is a gap for an agent to know how to interpret results.

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

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

Schema coverage is 100% (parameter 'key' already described as 'omit to list all keys'). The description reiterates this but adds no new semantic information 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 retrieves a value saved via 'remember' or lists all keys when omitting the key argument. It distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

The description provides concrete examples (target ticker, address, research notes) and explains when to use it ('without re-deriving it from scratch'). However, it does not explicitly state when not to use it or mention alternatives beyond the paired tools.

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

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

All annotations indicate read-only, idempotent, and non-destructive behavior. The description adds significant context beyond annotations by explaining that mark_read:true flags events as read and that subsequent calls only show newer events. This clearly communicates the tool's side-effect behavior.

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

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

The description is concise at 4 sentences, efficiently covering purpose, return fields, filtering options, marking behavior, and an alternative access method. Every sentence adds value, and the structure is logical and front-loaded.

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

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

The description adequately covers usage, filtering, marking, and alternative access. With no output schema and 5 optional parameters, it provides sufficient context for basic usage. However, it lacks information on error handling or pagination for large result sets, which would improve completeness.

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

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

Schema coverage is 100% with inline descriptions for all 5 parameters. The description enhances this by providing an example for the 'type' parameter (e.g., sec_8k) and explaining the functional effect of 'mark_read' (flagging as read to change future results). This adds meaning beyond the schema alone.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned data fields (source, citation_uri, raw payload). The verb 'pull' and resource are specific, and while sibling differentiation is not explicit, the purpose is unambiguous and distinct from other tools.

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

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

The description provides filtering guidance (type, since) and explains the mark_read behavior. It also mentions that polling works fine and notes an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly state when not to use this tool versus other sibling tools, missing some comparative guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds practical behaviors: multiple source fan-out, soft-fail for USPTO, date format flexibility, and return structure. 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?

Front-loaded with example queries; every sentence adds information. Slightly verbose with the piped examples, but no redundancy. Efficient for the complexity level.

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, description details return structure (changes grouped by source, total_changes, citation URIs). Covers all key aspects: sources, fallback, date formats, and distinguishes from sibling. Complete for the tool's complexity.

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

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

Schema covers all 3 parameters with descriptions. Description adds value by explaining shorthand syntax for 'since' and acceptable formats for 'value' (ticker or CIK). Some repetition but overall helpful.

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

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

Description clearly states the tool is a change feed for a company, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from sibling entity_profile with explicit alternative.

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

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

Provides explicit when-to-use examples (e.g., 'What's new with X'), fallback behavior (GDELT→GNews), and clearly directs to use entity_profile for static profiles. No ambiguity.

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

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

Beyond annotations, description reveals scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) sessions. 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?

Four sentences, each adding value. Front-loaded with purpose, then usage, then behavioral details. 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 no output schema, description could hint at return value or overwrite behavior. However, for a simple two-parameter tool, it provides essential context. Minor gap: doesn't state whether setting an existing key replaces it.

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

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

Schema covers 100% of parameters with descriptions. Description adds context like 'scoped by your identifier' and naming examples, but these are minor enhancements over schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions. Uses specific verb 'save' and resource 'key-value pair'. Distinguishes from siblings by naming `recall` and `forget`.

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

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

Explicitly instructs when to use ('when you discover something worth carrying forward') and provides examples. Mentions companion tools `recall` and `forget`, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: it explains graceful degradation (if GLEIF/OpenFIGI are unavailable, EDGAR identifiers still return), that it cascades through multiple lookup endpoints internally, that it returns figi_candidates when multiple matches exist, and that unresolved identifiers are explicitly listed under `unresolved` rather than omitted. This enriches the agent's understanding of what happens in edge cases and failure modes, going well beyond the annotations.

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

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

The description is a single, dense paragraph that runs on for many sentences. While every sentence adds relevant detail, the lack of bullet points or section breaks makes it harder to scan. It is front-loaded with the purpose and usage guidance, which is good, but the middle sections on LEI/FIGI enrichment and degradation are verbose and could be condensed. It earns a 3 because it is informative but not concise or 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?

For a tool with no output schema and only two parameters, the description covers a wide range of contextual needs: supported input types (ticker, CIK, ISIN, name for company; brand/generic for drug), handling of ambiguous matches, behavior when enrichment fails, and what fields appear in the response (identifiers with sources, `unresolved`, `figi_candidates`). It does not explicitly describe the full JSON response structure, but given the absence of an output schema, it provides sufficient detail for an agent to understand expected outputs and edge cases. A complete specification would include exact field names and nested structure, but the description is adequate for the task.

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

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

Schema description coverage is 100% for both parameters, but the description adds valuable nuance. For `type`, it explains the two supported values and their meaning. For `value`, it gives critical guidance: 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed... never the question's full noun phrase,' which is essential for correct invocation. It also explains that an ISIN resolves to the legal entity, not the security. These details are not present in the schema and significantly reduce misuse.

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

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

The description states a specific verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives multiple example phrasings and explicitly says 'Use FIRST whenever you have a name but need an ID,' which clearly distinguishes it from sibling tools by positioning it as the primary name-to-ID resolver. The supported types (company, drug) and core outputs (CIK, ticker, LEI, FIGI, RxCUI) are enumerated, leaving no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also specifies when the tool is appropriate for bond/issuer lookups, how to handle ambiguous matches (returns figi_candidates, asserts nothing), and that it replaces 2-3 manual lookups, reinforcing its role as the go‑to resolver. It clearly implies when not to use it (when you already have the ID or need a different type of lookup), though it doesn't name specific sibling tools as alternatives, but the guidance is strong enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. It does not contradict annotations and provides valuable behavioral context beyond the structured fields.

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

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

The description is three sentences, front-loaded with the core action, and every sentence adds value. No wasted words or redundancy.

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

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

Given the tool has moderate complexity, 4 parameters, no output schema, and annotations cover safety, the description adequately explains the return format (ranked list with score, confidence, signal density) and the probing mechanism. It is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds important context: the first entity in the entities array is treated as the 'subject' for narrative and the rest as competitors. This adds semantic meaning beyond the schema for the crucial entities parameter.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and surfaces most/least recognized. The verb 'compare' and resource 'AI presence' make the purpose specific. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a use case (competitive AI-marketing audits) and an example question. It implicitly suggests using ai_visibility_check for single entities, but does not explicitly list alternatives or when not to use this tool. The context is clear enough for most agents.

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, open-world, idempotent, non-destructive behavior. The description goes further by explaining partial failure handling and potential 5-30s delay on first bundlephobia measurement, with sources_failed field if timeout occurs. 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 well-structured with front-loaded purpose, clear usage guidelines, and detailed behavioral notes. Every sentence serves a purpose without redundancy.

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

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

Despite no output schema, the description thoroughly explains the return format (summary block, per-advisory detail, links, alternative versions) and ecosystem limitations. It covers partial failures and timing, making the tool's behavior fully predictable.

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 adds minimal parameter info beyond the schema (e.g., scoped packages accepted, default version behavior), but this is already present in schema descriptions. The description does not significantly enhance understanding of parameters.

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 that the tool performs a composite check for adding an npm package, combining deps.dev and bundlephobia data. It uses a specific verb-resource ('should I add this npm package' check) and distinguishes from sibling tools by highlighting its 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?

The description explicitly tells when to use this tool: when an agent asks about safety, popularity, size, or cost of adding a package. It also provides exclusions: NPM ecosystem only, and points to deps.dev:version 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?

The description adds significant behavioral context beyond the annotations: it reveals the use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char limit with truncation flagging, and that results include character offsets for verification. This fully informs the agent about operational details.

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

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

The description is two focused paragraphs: the first sentence defines the primary action, the second explains the use case, and the third provides technical details. Every sentence contributes unique information without 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?

Despite lacking an output schema, the description fully explains what the tool returns (top-N passages with offsets and scores) and its technical limits. It also covers usage context and pairing with a sibling tool, making it self-contained for a tool with three 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 value by providing concrete examples for 'text' (SEC 10-K, article) and 'query' (supply-chain risk, revenue queries), and clarifies the natural-language nature. This moves it above baseline.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the verb 'search', the resource 'fetched record', and the scope. It distinguishes from siblings by contrasting with full-document tools and explicitly mentioning the 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?

The description explicitly advises when to use the tool: when the record is too large for the prompt, and it recommends pairing with ask_pipeworx_grounded for grounding. This provides clear context and alternatives, exceeding minimal 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 adds useful behavioral detail beyond annotations, such as authentication requirements, rate limits (10/day cap for SMS), and delivery channel specifics. However, there is a contradiction: the 'idempotentHint' annotation suggests idempotency, but the description says 'Returns the new subscription id' implying a new subscription on each call, which may not be idempotent.

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

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

The description is well-structured: it starts with the core action, then prerequisites, followed by type-specific details, and finally delivery channels. Every sentence serves a purpose, and it is not overly verbose for the complexity of the tool.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, prerequisites), the description covers most aspects adequately. However, there is no output schema, and the return value is only briefly mentioned ('returns the new subscription id'), lacking details like the id format or how to access it.

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

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

Even though schema description coverage is 100%, the description adds significant value by providing concrete examples and explanations for each parameter, especially the 'params' object and 'delivery' object. This helps an AI agent understand how to construct valid inputs.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource ('subscription'), and distinguishes it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description provides clear contexts for use, including prerequisites ('Requires a Pipeworx OAuth account') and examples for each subscription type. However, it does not explicitly state when not to use this tool or mention alternative tools for monitoring (e.g., using 'recent_alerts' without creating a subscription).

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

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

Annotations already declare readOnlyHint and idempotentHint, so no safety contradiction. The description adds useful behavioral context about returning category-bucketed examples with exact tool shapes, but doesn't repeat annotations.

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

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

The description is relatively long but well-organized, front-loads the use case, and packs in examples and guidance without unnecessary fluff. A slight trim could improve conciseness.

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

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

Given no output schema, the description adequately explains what the tool returns (category-bucketed examples with tool details). It also mentions the live catalog. It is complete enough for a simple read-only tool.

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

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

The description adds significant meaning to the single optional 'topic' parameter by listing example values and explaining that omitting it gives a cross-category spread. This goes beyond the schema's basic description.

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

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

The description clearly states it's an onboarding entry point that returns category-bucketed example questions. It distinguishes from siblings by explicitly recommending to 'use this FIRST when you do not yet know what Pipeworx can do for you'.

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

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

The description provides explicit when-to-use scenarios (user asks 'what can I ask?', 'getting started') and suggests using it before other tools. It doesn't explicitly state when not to use or list alternatives, 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?

Beyond annotations (destructiveHint=false, etc.), the description adds that ownership is enforced and the row is deactivated, not deleted, so historical events remain. This provides behavioral context that annotations alone do not fully cover.

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

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

The description is extremely concise with two sentences, no fluff, and front-loaded with the action. Every sentence adds value, making it highly efficient for an AI agent to parse quickly.

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 cancelation tool with one parameter and no output schema, the description covers ownership, the soft-delete behavior, and references related tools for historical data. It is fully sufficient for an agent to understand and use 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 sole parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no new meaning beyond the schema, so a baseline score of 3 is appropriate given 100% schema coverage.

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

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

The tool name 'unsubscribe' and title 'Unsubscribe from Alerts' clearly indicate its purpose. The description states 'Cancel a subscription by id' with a specific verb and resource, and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement and the effect (deactivation, not deletion), providing clear context for when to use the tool. It also cross-references 'recent_alerts' for historical events, but does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds crucial behavioral nuance beyond that: it explains that 'could_not_verify' means the check did not happen and must not be treated as evidence, and contrasts this with 'unsupported' (no coverage). This is exactly the kind of context (error semantics, evidence interpretation) that annotations cannot convey and prevents misuse.

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

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

The description is dense but well-structured: it front-loads natural-language triggers, explains the two routing paths, enumerates verdict types, and clarifies error cases. Every sentence contributes information, and the length is justified by the tool's complexity. It is not as tight as a two-sentence ideal, but it avoids waste.

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

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

Despite no output schema, the description fully documents the return payload (verdict, actual value with citation, reasoning) and the meanings of each verdict. It also covers failure modes (could_not_verify, unsupported), the tolerance_pct parameter, and how this tool replaces multiple sequential calls. For a tool with this complexity, the description is complete and self-contained.

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

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

Schema covers both parameters at 100%, so the baseline is 3. The description adds real value by explaining tolerance_pct defaults/override behavior and giving a concrete use case (set 1-2 for hallucination detection). That goes beyond the schema's simple data type description and helps the agent choose parameter values appropriately.

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

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

The description opens with concrete invocation phrases and clearly states the tool's function: natural-language claim verification against authoritative sources. It explicitly distinguishes between the structured SEC EDGAR fast path for company-financial claims and the grounded pipeline for all other factual claims, which also differentiates it from sibling tools like query, deep_research, 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?

Explicit 'Use whenever the agent needs to check whether something a user said is factually correct' gives clear invocation context. It also provides routing guidance (company-financial vs. other claims), recommendations for tolerance_pct in hallucination detection, and clarifies that it replaces 4–6 sequential calls, helping an agent decide when to call this tool directly.

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