Arcgis Salem

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

Given the annotations already declare readOnlyHint and idempotentHint, the description adds useful context: the default model is free, and passing `_apiKey` incurs direct Anthropic charges. It also discloses that the key is 'passed straight through to api.anthropic.com', which clarifies data flow and privacy implications.

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 core purpose is front-loaded in the first line. The rest of the description packs essential details (default, cost, return structure) without filler. Every sentence earns its place, and the total length is appropriate for 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?

Even with no output schema, the description explains what is returned ('per-model {score, confidence, signals, raw_response} + a combined view') and provides use cases. It could mention the combined view's interpretation or the exact list of supported models, but overall it's sufficiently complete for selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the default model ('Workers AI Llama-3.3-70b (free)') and the conditional need for `_apiKey` ('only needed if "anthropic" is in models'). This goes beyond the schema's per-parameter docs.

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

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

The description opens with a specific verb ('Probe'), names the resource ('one or more LLMs'), and defines the outcome ('score visibility (0-100) per model'). This clearly distinguishes the tool from siblings like ask_pipeworx or deep_research by focusing on what LLMs know about an entity.

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

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

It explicitly names use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't explicitly mention when NOT to use it or point to alternatives like scan_competitor_ai_presence, but the context is clear enough for an agent to select it.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable behavioral context: routing to thousands of sources, filling arguments automatically, returning stable citation URIs, working on every tier, and being a single fast call. It does not contradict annotations, though it does not cover potential failure modes or response format edge cases.

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 critical 'PREFER OVER WEB SEARCH' directive and immediately states the tool's scope. It is long but every sentence carries strategic information: source coverage, routing mechanism, output format, usage triggers, examples, and escalation paths. 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?

Despite having no output schema, the description explains what the return value looks like ('structured answer with stable pipeworx:// citation URIs'). It covers alternatives, example queries, and even clarifies boundary cases like breaking news. For a tool of this complexity (routing across thousands of sources), the description is remarkably complete.

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

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

Schema coverage is 100% (all parameters are aliases for 'question'). The description adds semantic value by providing six concrete example questions that clarify expected natural-language input, going beyond the bare schema 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 uses a specific verb 'routes the question' and identifies the resource: a meta-tool that selects among 5,462 tools across 1,419 verified sources, returning structured answers with citations. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

Explicit when-to-use guidance is given: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also states when to step up to alternatives ('Step up only when needed') and provides examples of question types that fit. This is a textbook example of usage guidance.

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

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

Annotations declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about live candidate routing, the current inactive state, and the fact that it is a full working router, not a stub. This enhances transparency without contradicting annotations.

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

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

The description is well-structured and concise, front-loading the beta identity, then covering current state and usage. Each sentence contributes essential information with no redundancy or filler.

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

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

For a complex beta router, the description covers identity, current active state, usage instructions, and its relationship to the stable router. It also notes the same response shape, providing expectations despite the lack of an output schema.

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

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

Schema coverage is 100%, with all six parameters documented (five aliases for 'question'). The description does not add parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. It differentiates itself from the stable sibling by identifying the experimental routing improvements and its current 'live when under test' status.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and clarifies that results are compared against the stable router, making the use case and distinction 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 the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses add behavioral details such as the exact refusal reasons ('not_in_source', 'no_tool_match', 'tool_error', 'data_truncated', 'llm_error'), the one extra LLM call cost, and the strict grounding behavior. This goes well beyond what annotations provide.

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

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

The description is a five-sentence paragraph where every sentence adds value: purpose, mechanism, output contract, usage guidance, and cost trade-off. It opens with the strongest differentiator and remains concise despite the complexity.

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

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

With no output schema, the description fully specifies the return format on both success and failure, including the evidence field and refusal reasons. It also covers usage context and the cost trade-off, making the tool's behavior entirely self-explanatory for a complex grounded-answer 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?

All six parameters are aliases for the single 'question' input, and the schema provides 100% coverage by describing each alias and the main field as 'Your question in natural language.' The description adds no additional parameter-level detail, so a baseline score of 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode' and explains it 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes itself from sibling ask_pipeworx by mentioning 'Same routing as ask_pipeworx' while adding stricter grounded extraction, making the purpose unambiguous.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool directly, making the choice between siblings clear.

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

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

The description goes far beyond the read-only annotations by detailing response shapes, resolver match confidence, parent-event extraction, news fallback behavior, low-confidence short-circuiting, closed-market status, wide-spread market handling, and cancellation-rule parsing. This provides comprehensive behavioral disclosure beyond what annotations offer.

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 and well-structured with section headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). The first sentence front-loads the purpose, and each section adds distinct value. While long, the organization justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly documents result fields, match confidence levels, parent-event data, news fields, safety mechanisms, and cancellation-rule risks, making it complete for an agent to invoke and interpret results correctly.

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

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

The input schema already provides 100% coverage with clear descriptions for market, depth, and include_raw. The description adds minimal parameter-specific detail beyond what the schema states; the fan-out examples illustrate depth but don't introduce new parameter semantics. Baseline of 3 is appropriate given full schema coverage.

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

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

The opening sentence 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' clearly defines the verb, resource, and scope. The 'Use for' line adds explicit intended use cases, and the detailed fan-out examples distinguish it from sibling tools like polymarket_arbitrage or 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 explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear when-to-use guidance. It does not explicitly name alternative tools or list when-not-to-use scenarios, but the scope is clearly distinct from 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?

Annotations already declare readOnly/idempotent, and the description adds rich context: data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, handling of off-calendar fiscal years, and citation URIs. 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?

Description is densely packed with useful information, front-loaded with trigger phrases, and every sentence contributes to understanding usage, data sources, or behavior. No filler or redundancy.

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

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

For a tool with 2 params and no output schema, the description is comprehensive: it explains use cases, data sources, return format (paired data + citation URIs), sorting, and edge cases (off-calendar fiscal years). It fully equips an agent to select and invoke correctly.

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

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

Schema covers both parameters with 100% description coverage; the description further explains what each 'type' value pulls (e.g., company pulls 10-K revenue, drug pulls FAERS counts), and provides examples for the 'values' parameter. Adds meaningful type-specific semantics beyond the enum labels.

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 performs side-by-side comparison of 2–5 companies or drugs in one call, with explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes from siblings by emphasizing it replaces sequential single-pack lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use and implicit exclusions. Also gives concrete examples of user intents and explains the parallel-call advantage.

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

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

Description discloses substantial behavioral traits beyond annotations: requires account (paid for thorough), returns gaps[] when data can't answer, includes contradictions[] for deeper depths, semantically excerpts large records, has expected latency, and ensures citations are always fetchable. Annotations already declare read-only/open-world/idempotent, and description adds context without contradiction.

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

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

Description is long but each sentence carries important caveats (account, alternatives, latency, gaps, citations). It is front-loaded with the account requirement and uses paragraph breaks to structure key sections. Slight verbosity prevents a 5, but it avoids waste for such a complex tool.

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

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

Given high complexity, two parameters, no output schema, and no formal output schema, the description fully covers return behavior (findings packet, gaps, contradictions, hop field, citation_uri), prerequisites, alternatives, error cases (empty gaps for news topics), and time expectations. It is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining depth levels in context (e.g., 'standard' re-angles unanswered gaps, 'thorough' requires paid plan, 'quick' single-hop) and noting that question can be broad/multi-part. This enriches the schema's already-detailed 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?

Description clearly states a specific verb ('research') and resource ('Pipeworx's 1419 STRUCTURED data sources'), and explicitly distinguishes from open-web search and sibling ask_pipeworx. It describes a multi-source, parallelized research tool with a findings packet, uniquely positioning it 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?

Explicitly provides when-to-use guidance and alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and says to use ask_pipeworx if not signed in. This clearly differentiates from sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds valuable behavioral context beyond that: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and it says results are 'ready to call directly, no second schema lookup needed.' This sets expectations for output format and workflow integration.

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

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

The description is four sentences and front-loaded with the core purpose. The long list of data domains is somewhat verbose but directly informs the agent about the tool's coverage, making it useful rather than fluff. Every sentence earns its place: purpose, when-to-use, output description, and a strong strategic call-to-action ('Call this FIRST').

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

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

The tool is simple in structure (one required param, no output schema), but the description fully compensates for the missing output schema by explaining what will be returned (top-N tools with full schemas and examples). It also covers when to invoke it and what to expect. For a meta-tool whose main job is to surface other tools, the description is complete and actionable.

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

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

Schema description coverage is 100%, so the schema already explains every parameter including aliases and examples. The description adds minimal but useful meaning: it clarifies the query is a 'natural language description' and mentions the 'top-N' behavior tied to the limit parameter. This is slightly above baseline because the description reinforces the query's free-form nature and the limit's role.

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: 'Find tools by describing the data or task.' It specifies a concrete verb ('Find'), a resource ('tools'), and the mechanism (describing data/task). It also distinguishes itself from siblings by focusing on tool discovery rather than dataset search or other specific functions, and it lists many data domains to clarify 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 explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear when-to-use guidance. It also implies alternatives (if you already know the tool, you don't need discovery) without cluttering the description.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaningful behavioral details: patents 'soft-fails until reactivated', news uses 'GDELT→GNews fallback', and fundamentals are 'LATEST 10-K' sorted. This goes beyond the safety annotations and discloses limitations and fallbacks, though rate limits or parallel execution details are not covered.

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 structured with semicolons and lists, and each sentence adds value. It's front-loaded with example prompts, then details output fields and limitations. While dense, it avoids fluff and earns the length, though a more scannable layout would be slightly better.

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 clearly enumerates the return fields (cik, recent_filings, fundamentals, patents, news, LEI), gives input examples, explains fallback behavior, and states limitations. For a complex multi-source tool, it is unusually complete and actionable 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 already documents both parameters with 100% coverage, but the description adds examples ('AAPL', '0000320193') and emphasizes that names are not supported, reinforcing the value format. It also clarifies that 'type' only supports 'company' for now, which is in the schema but phrased more concretely in the 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 explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' and lists exact data types (filings, fundamentals, patents, news, LEI). It distinguishes from siblings by specifying sources and output fields. The verb-like phrases ('Tell me about X', 'brief me on Tesla') clearly show the tool's purpose.

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

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

It gives explicit usage rules: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'Names not supported (use resolve_entity first if you only have a name)'. This clearly states when to use and points to an alternative tool, which is better than typical descriptions.

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 disclose destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds useful context about what gets destroyed (previously stored memory) and mentions clearing sensitive data, which goes beyond the annotations. However, it doesn't elaborate on permanence or error handling, but the annotations cover the core behavioral traits.

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

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

Three sentences, each with a clear purpose: the first states the action, the second gives usage scenarios, the third points to related tools. There is no fluff, and the most important information is 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?

For a simple one-parameter delete tool, the description covers the purpose, when to use it, and its relationship to siblings. Annotations handle the safety profile (destructive, idempotent). The lack of an output schema is acceptable. It could mention what happens if the key doesn't exist, but the idempotentHint already implies a safe no-op, making the description sufficiently complete.

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

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

The schema has 100% coverage: the single parameter 'key' is described as 'Memory key to delete.' The description merely repeats 'by key' without adding details about key format, origin, or constraints. The schema already carries the semantic weight.

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: 'Delete a previously stored memory by key.' It identifies the resource (memory) and the identifier (key), and it distinguishes itself from sibling tools like 'remember' and 'recall' by specifying deletion.

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 scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), giving clear guidance on how it fits into a workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt format, ready for site-root placement.

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 and front-loaded with the core action, followed by a brief process summary and a 'Useful for' list. Every sentence serves a purpose, with no unnecessary elaboration.

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 moderate complexity, the description covers the action, output format (standard llms.txt markdown, single text blob), and use cases. Without an output schema, it adequately explains the return value. It could mention limitations, but the provided context is sufficient for an agent to use it correctly.

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

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

Schema coverage is 100%, so both parameters (url and max_links) are fully documented in the schema. The description does not add any parameter-specific details beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's action ('Generate a production-ready llms.txt file'), the resource ('for any URL'), and its specific function (fetches, extracts, emits standard markdown). It is distinct from sibling tools like scan_competitor_ai_presence, which focus on auditing presence rather than generating the file.

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 ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context. However, it does not name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds output details but no deeper behavioral context (e.g., rate limits, URL format quirks). It adds minimal value beyond annotations.

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

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

A single, well-structured sentence packs the primary verb, resource, and expected outputs without fluff. Every word earns its place, making it easy 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?

Given the tool's simplicity (one parameter, no output schema), the description sufficiently lists the return contents (fields, geometry, count, capabilities). A slight gap is that 'capabilities' is not explained, but this is minor for a schema introspection 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?

There is only one parameter (url) with 100% schema description coverage. The description repeats 'by url' but does not add extra meaning like accepted URL forms or error conditions. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource: an ArcGIS Feature/Map Service layer's schema. It enumerates the exact outputs (fields, geometry type, record count, capabilities), distinguishing it from sibling tools like query_layer, which likely retrieves data rather than 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 phrase 'by url' establishes the clear context for when to use this tool (when you have a layer URL and need schema information). It does not explicitly list alternatives or exclusions, but the scope is unambiguous for a schema retrieval operation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ('caller's active subscriptions'), which is beyond the annotations. No contradictions found.

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 exactly two sentences. The first sentence states the action and return fields, the second gives usage context. There is no filler or redundancy—every clause 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 appropriately lists the return fields, providing necessary information for the agent to interpret results. The tool is simple (one optional parameter) and the description covers its purpose, return shape, and usage scenario, making it sufficiently complete for this complexity level.

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% for the single parameter include_inactive, meaning the schema already fully describes it. The description does not add additional syntax or format details beyond the schema. Per the guidelines, baseline is 3 when schema coverage is high, and the description does not meaningfully augment the parameter semantics.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' This includes a specific verb ('List') and resource ('subscriptions'), and distinguishes it from sibling tools like subscribe/unsubscribe by focusing on read-only listing. It also enumerates the returned fields, making the function concrete.

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 offers clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't explicitly name alternative tools, this guidance implies when it should be used relative to subscribe/unsubscribe, which are the obvious siblings. It provides practical scenarios for the agent.

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

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

Annotations are all false (not read-only, etc.), so description carries the burden. It adds valuable context: return of a claim_token for anonymous follow-up, rate limit of 5 per identifier per day, exemption from tool-call quota, and the rule about not pasting end-user prompts. 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 (approx. 150 words) but each sentence serves a distinct purpose: action, use cases, exclusions, claim_token mechanics, rate limits, and usage etiquette. It is front-loaded with the primary verb and resource, and the structured flow makes it efficient despite the length.

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

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

Given no output schema and neutral annotations, the description fully equips the agent to decide when and how to invoke: it covers purpose, eligibility boundaries, token-based follow-up, rate limiting, and quota-free nature. The only return value (claim_token) is explained, so no critical context is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explaining the claim_token lifecycle (filing returns it, passing it back later reads status), and provides illustrative examples for the context object (pack 'fred', tool 'fred_get_series'). This meaningfully enriches parameter understanding.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature/data_gap, praise) and explicitly distinguishes this from sibling tools (which are all research/query 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?

Provides explicit when-to-use scenarios for each feedback type, and explicit when-not-to-use with an alternative: 'if the tool came from a different MCP server... file it with that server instead.' Also clarifies how to identify Pipeworx tools, giving unambiguous 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 valuable behavioral context beyond the readOnly/openWorld/idempotent annotations: self-aggregating signal, derived from CF analytics-engine, no PII, and cached for 5min-1h. This explains data provenance, privacy, and freshness, which annotations do not 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 well-structured and front-loaded: first sentence states purpose, then returns, then use cases, then technical details. Each sentence earns its place, and there is no redundant or filler content.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers return values (top tools, packs, count), data source, privacy, and caching. It provides a complete picture of what to expect, fitting 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?

The input schema already fully documents the single window parameter with enum values, default, and effects (24h, 7d, 30d). The description mentions the window but does not add new semantic meaning beyond the schema. Baseline 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 description clearly states what the tool does: returns top tools, top packs, and total call volume of agent calls on Pipeworx over a selected window. It distinguishes itself from sibling search/discovery tools by focusing on aggregated trending signals, not individual 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?

The description explicitly provides three use cases: discovering hot data sources, confirming a canonical tool, and checking alignment with other agents. It gives clear context for when to use the tool, though it does not name alternative tools or exclusions explicitly.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral detail: thresholds (>3pp produce a signal), similarity filter (≥0.30 Jaccard), placeholder filtering (>20% returns null), and the crucial 'FILL CHECK' caveat that realizable_edge_pp ≤ 0 means the edge exists only at last-trade and should not be traded. It also discloses the response shape including opportunity fields and partition_check, which is critical without 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?

The description is long but well-structured with clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and mode-specific bullets. Every sentence adds meaningful detail, and the front-loaded main purpose makes it easy to scan. It is slightly longer than necessary, but the density of crucial trading logic justifies the length.

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

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

Given the tool's complexity—multiple modes, thresholds, edge cases, and a fill-check integration—the description is remarkably complete. It explains the response structure, provides interpretation guidance for results (e.g., 'do not trade it'), links to a sibling for custom sizing, and covers parameter semantics. With no output schema, the description successfully compensates by detailing return values and operational nuances.

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 goes far beyond the schema by providing concrete slug examples ('fed-decision-may-2026'), explaining full URLs are accepted, and clarifying the behavioral difference between `event` and `topic` modes. It also implies mutual exclusivity ('pass `event` for... or `topic` for...') and describes the downstream effects of each parameter, adding significant meaning beyond the input schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and referencing custom sizing to a sibling. The three modes (trending_scan, event, topic) are explicitly defined with concrete examples.

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

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

The description gives explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also directs users to 'use polymarket_fill_risk' for custom sizing, naming an alternative. However, it does not explicitly contrast with other sibling tools like polymarket_edges or polymarket_edge_tracker, leaving some comparison implicit.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds substantial behavioral context: 1h KV caching keyed on knobs, the 24h-move warning, fed_candidates excluded due to unreliable signal, rare-by-design concentrated longshot, and diagnostics showing why segments may be empty. This goes well beyond the safety annotations and arms the agent with operational expectations.

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

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

The description is long but information-dense. It front-loads the purpose and then systematically covers model families, response structure, and parameter semantics. Each sentence contributes unique value; there is no fluff. It could be better structured with headings, but for a complex tool this density is justified.

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

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

With 9 parameters, no output schema, and no nested objects, the description carries full burden for return semantics and edge cases. It explains the response top-level fields (by_segment, fed_candidates, _diagnostics), the meaning of edge_pp_net/kelly, and the funnel counters. It even discloses the caching behavior. This is exemplary completeness for a complex analytical tool.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining the conceptual role of tradeable-edge knobs (e.g., min_liquidity/max_spread_pp) and the special semantics of min_partition_leg_kelly (why parent-level min_kelly doesn't filter partition arbs). This adds meaning beyond the schema's already thorough property descriptions.

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

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

The description opens with a clear, specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes itself from siblings by detailing the five model families across three segments, making its unique value explicit. This is far more differentiated than typical tool descriptions.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This tells the agent when to use it. It does not explicitly contrast with sibling tools, but the rich detail about segments and knobs implies how to narrow usage. Missing explicit 'when not to use' guidance, but the context is strong.

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

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

The description goes far beyond the annotations by explaining critical behavioral details: snapshots are written on cache-miss causing gaps, history is bounded by a 60-day TTL and snapshotting enablement, decay numbers derive from daily closes net of default slippage rather than intraday data, and the response includes expired opportunities with their lifespan. These are non-obvious behaviors an agent needs to correctly interpret results.

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

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

The description is long but exceptionally well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds meaningful information: core purpose, parameter explanations, response anatomy, and limitations. The most critical context (what the tool answers) is front-loaded, and the formatting makes it easy for an agent to parse.

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

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

Given the tool's moderate complexity (2 optional params, no output schema), the description is remarkably complete. It specifies the return structure (tracked[], expired[], snapshot_dates[]) with semantic details, explains edge cases (snapshot gaps, TTL limits, signed values, trend classification), and even clarifies the meaning of negative edge values. No critical information is missing.

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

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

The input schema already covers both parameters with clear descriptions (100% coverage), so the baseline is 3. The description adds value by clarifying that 'days' controls lookback (default 14, max 30) and 'window' selects a snapshot family (default '1wk'), and by explaining how these parameters relate to snapshot data availability. This enriches the schema without redundancy.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from the sibling 'polymarket_edges' by focusing on historical persistence and decay rather than current edge data.

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

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

The description implies when to use this tool by contrasting fresh edges with older ones ('a fresh wide edge and a 3-week-old wide edge are different trades'), which tells the agent this is for evaluating edge age and decay. It references the parent tool 'polymarket_edges' as the source of snapshots, giving context, but does not explicitly state 'use X instead for current edges' or list when-not-to-use scenarios.

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, non-destructive, and idempotent behavior. The description adds rich behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and warns that partial basket fills create unhedged directional risk — a key loss mode. This supplements annotations without contradiction.

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

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

The description is long but dense, with each sentence carrying significant information. It front-loads the core purpose and uses uppercase markers to distinguish modes. Could be broken into bullets for readability, but 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 compensates by enumerating all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, etc.), verdict values, and risk flags like thin_legs and forced_directional_risk. This is comprehensive enough for an agent to act correctly.

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

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

Schema covers 100% of parameters, but description adds crucial semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode, 'settlement notional — shares per leg' in basket mode; side defaults to auto in basket; market and event are mutually exclusive. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' — a specific verb+resource+scope. It distinguishes itself from siblings by explicitly instructing use before polymarket_arbitrage or polymarket_edges trades.

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

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

Provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also details two modes (single-market vs basket) and clarifies when each applies, including default behavior.

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

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

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses extensive behavioral details: compatibility_warning triggers, temporal_alignment and its implications for spread validity, skipped_cross_type/subtype counters, and the explicit statement that pre-mapped ≠ tradeable. This goes far beyond what annotations alone convey, making the tool's safety and failure modes transparent.

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

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

The description is long but well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence delivers useful semantic or safety information. The final warning 'pre-mapped ≠ tradeable' is slightly redundant with the preceding sentence, preventing a perfect 5, but the structure earns a strong 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?

With no output schema, the description fully accounts for response shape (leg-by-leg prices, spread[].top_spreads_pp), compatibility warnings, temporal alignment, and skipped comparison counters. It leaves no critical decision factor unaddressed for a complex dual-venue analysis tool, making it exceptionally complete.

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

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

Although the schema covers 100% of parameter descriptions, the description adds meaningful relational semantics: it explains that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and it enumerates the exact topic shortcuts. This gives agents a clear mental model of parameter precedence and pairing logic, exceeding baseline schema credit.

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

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

The description opens with a specific verb+resource+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This immediately distinguishes the tool from likely intra-venue siblings like polymarket_arbitrage. It also elaborates on two modes, response contents, and safety fields, making the purpose unmistakable.

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

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

The description clearly explains when to use the tool—for cross-venue spreads where bet shapes are equivalent—and when the output will indicate no arb exists. It provides context around the two modes (topic vs explicit) and warns that most pre-mapped topics return compatibility_warning, effectively giving when-not-to-use guidance. However, it does not explicitly name alternative tools for comparison.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds useful behavioral detail: returns attribute rows and optionally geometry, and supports pagination via limit/offset. This goes beyond the annotations without contradicting them.

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

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

Three concise sentences: purpose, parameter summary, and a useful usage tip. Front-loaded with the main verb and resource. 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?

No output schema exists, but the description explains what is returned (attribute rows and geometry). It provides source context (search_datasets) and a sampling workflow. Missing edge-case/error behavior, but for a read-only query tool with well-documented schema, coverage is strong.

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 value by calling out the SQL-like nature of `where`, comma-separated `out_fields`, and the practical sampling pattern, slightly enhancing param understanding beyond the schema.

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

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

Clearly states it queries an ArcGIS Feature Service / Map Service layer by URL, identifying the specific verb, resource, and data-returning nature. Distinguishes from siblings like search_datasets (search vs query) and layer_info (metadata vs data).

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

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

Gives clear context that the URL comes from search_datasets and provides an explicit sampling tip (where="1=1" + out_fields="*"). However, it does not explicitly name alternatives or when-not-to-use exclusions, so it falls 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, idempotentHint=true, and destructiveHint=false. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key to list all keys. 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, each earning its place: core action, usage context, and scope. The description is front-loaded and free of fluff.

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

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

For a one-optional-param read tool with strong annotations, the description covers purpose, usage, scoping, and sibling relationships. The lack of an output schema is mitigated by language that clearly states what is returned (a value or list of keys).

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 value by explaining the 'omit the key' behavior and giving concrete examples ('target ticker, an address, prior research notes'), which help the agent decide what to pass.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes this from sibling tools like remember and forget by naming them directly.

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

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

Explicit guidance: 'Use to look up context the agent stored earlier' and pairing with 'remember to save, forget to delete.' This gives the agent clear when-to-use and relationship 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?

The annotation readOnlyHint=true contradicts the description's disclosure that setting mark_read:true flags events as read, a state mutation. This is an annotation contradiction, so the description conflicts with the declared safety profile.

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 purpose. Adds filtering, mark_read behavior, and external access without waste. Each 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?

Even without an output schema, the description explains return payload fields (source, citation_uri, raw payload). It also covers mark_read side-effects and the external feed URL, making the tool's usage fully understandable.

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

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

Schema already describes all 5 parameters. The description adds useful context beyond schema: gives an example for type ('sec_8k'), clarifies since as ISO timestamp, and explains the side-effect of mark_read. This enhances parameter understanding.

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

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

The description clearly states it pulls fired events from the subscription feed, with specific verbs and resource. It distinguishes itself from sibling tools like recent_changes by focusing on alerts from the feed.

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

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

Provides clear usage context: mentions polling works fine and offers an external HTTP endpoint for scripts/dashboards. It doesn't explicitly exclude alternative tools but implies the polling use case.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: parallel fan-out to SEC EDGAR, GDELT→GNews fallback logic, USPTO soft-fail due to API sunset, and the exact return shape (changes[], total_changes, citation URIs). This goes well beyond the annotation baseline.

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 but every clause serves a purpose: example queries, core function, source details, fallback, return format, and alternative tool. It front-loads with the most actionable examples and stays efficient despite the tool's complexity.

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

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

Given the tool's complexity (three data sources, fallback logic, soft-fail, date parsing, return structure) and the absence of an output schema, the description fully compensates. It specifies the return format, the accepted `since` formats, and the alternative tool for static profiles. Nothing essential is left unstated.

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 each parameter is already described well (type, format, examples, typical values). The description adds no new parameter-level semantics; it only rephrases the window concept. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with concrete example phrasings, then states the core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes itself from the static entity_profile tool by explicitly recommending entity_profile for static profiles. The verb+resource is specific and 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?

Provides explicit when-to-use guidance via example queries and a clear alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also details fallback behavior (GDELT→GNews) and soft-fail conditions, giving a nuanced picture of when results may vary.

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, the description adds persistence semantics: 'scoped by your identifier', 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. This discloses behavioral traits not present in the annotations, though it doesn't explicitly describe overwrite behavior (idempotentHint covers that).

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

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

The description is compact yet informative, front-loading the primary purpose. Each sentence earns its place — purpose, usage, persistence, and companion tools — without redundancy. Slightly longer than the two-sentence ideal but still efficient.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, and relationships to sibling tools. It doesn't detail return values (not needed) but is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with both key and value described in detail including examples. The description mentions 'key-value pair' but adds no new parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It distinguishes from siblings by explicitly referencing recall for retrieval and forget for deletion, clearly positioning remember as the storage companion.

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 usage scenarios: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also names complementary tools, making the when-to-use vs alternatives unambiguous.

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 readOnly, idempotent, and non-destructive, but the description goes beyond by detailing the exact output fields (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug), the auto-disambiguation behavior, and the internal cascading through multiple endpoints. This adds valuable context beyond annotations without contradiction.

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

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

The description is well-structured and front-loaded with example queries, immediately establishing purpose. It then provides usage guidance and detailed per-type output information, all in a compact, organized manner. Every sentence contributes value, with no fluff 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 the tool's moderate complexity (two parameters, one enum, no output schema), the description is remarkably complete. It covers purpose, when to use, input formats, output fields, citations, and internal behavior. The absence of an output schema is compensated by explicit return-value descriptions for both supported types.

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 examples and clarifies that 'value' accepts multiple formats (ticker, CIK, or name for company; brand or generic name for drug) and mentions auto-disambiguation, which goes slightly beyond the schema's own descriptions. However, much of this is redundant with the schema, only marginally enriching parameter understanding.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers required by other tools. It provides concrete example queries and explicitly differentiates from siblings like entity_profile by focusing on ID lookup. The scope is precise: returns ticker/CIK for companies and RxCUI for drugs.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also contrasts with manual lookups by stating it replaces 2-3 manual steps, and implies it should be used before other tools that require identifiers. This is a clear when-to-use directive, though it lacks explicit when-not-to-use 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 convey read-only, idempotent, open-world behavior. The description adds useful behavioral context by revealing it probes with ai_visibility_check and returns a ranked list with score, confidence, and signal density, which goes beyond the annotations.

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

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

Three sentences, each earning its place: what it does, how it works, and when to use it with return information. No filler, front-loaded action.

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

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

Given the lack of an output schema, the description compensates by naming return fields (score, confidence, signal density). It also covers the use case, behavior, and dependency on ai_visibility_check, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not add parameter-level detail beyond what the schema already provides (e.g., entities, models, _apiKey, context are all documented in the schema).

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), then details the mechanism (probes with ai_visibility_check, ranks by score). It clearly distinguishes from siblings by positioning itself as a multi-entity comparison rather than a single check.

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 a concrete use case (competitive AI-marketing audits) with an example question, which clearly implies when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it falls 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?

The description adds substantial behavioral context beyond annotations: it describes the fan-out nature, partial failure degradation, a 5-30s first-measurement timeout, and the sources_failed mechanism. This goes well beyond the readOnly/idempotent hints already provided.

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

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

The description is dense but every sentence earns its place, covering purpose, usage, output structure, ecosystem scope, and failure behavior. The main purpose is front-loaded, and no redundancy or fluff is present.

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 enumerates the exact return fields, lists per-advisory details and links, and explains timeout behavior. For a composite tool of this complexity, this is a complete and self-sufficient description.

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

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

The input schema already covers both parameters fully (package name, optional version with default). The description adds minimal extra param meaning, only hinting at usage context. Baseline 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 description opens with a specific verb+resource: a composite npm package evaluation check, naming both deps.dev and bundlephobia and their respective data. It clearly distinguishes this tool from sibling scanners by pinning the scope to npm packages and the exact question it answers ('should I add this npm package?').

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 ('whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"') and provides a direct exclusion: non-npm ecosystems should use deps.dev:version directly. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by listing the exact return fields (name, summary, record_count, owner/org, url) and the fact that the url is meant for downstream layer tools, which is not captured by 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 sentence that front-loads the tool's purpose and follows with the return value details. Every clause is informative and there is no redundant wording.

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

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

The description covers the tool's role, scope, return fields, and downstream usage, which is sufficient for a simple read-only search tool with fully documented schema. It does not mention optionality of query or pagination, but these are minor gaps given the schema coverage.

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 all three parameters (query, limit, org_id) are described. The description does not add any additional parameter-specific meaning; its mention of 'keyword' merely mirrors the query parameter 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 explicitly states the tool 'Search City of Salem GIS open geospatial datasets by keyword' and lists example content categories. It also names the return fields and directs the user to query_layer/layer_info, which distinguishes it from those sibling tools.

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

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

It implies the tool is for dataset discovery and that the returned URL should be used with query_layer/layer_info, providing a clear workflow. However, it does not explicitly state when not to use it or mention alternative discovery tools, so it lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavior beyond these annotations: it returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char overlapping windows, and documents a 200K-char cap with truncation flagged. 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 multi-sentence but every sentence earns its place: purpose, use case, pairing, technical details, and truncation behavior. It is front-loaded with the core action and avoids redundancy, though slightly dense with the embedding/windowing details. Still, it is appropriately sized for 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?

There is no output schema, so the description must explain return values — and it does: 'get back the top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation and flagging) and pairs the tool with a sibling, making it complete for a 3-parameter search tool with strong annotations.

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

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

The input schema covers all 3 parameters at 100% coverage. The description adds semantic value by contextualizing the 'text' parameter (e.g., 'a SEC 10-K body, an article, a long tool result') and by explaining the 'query' as a natural-language request. It also reveals truncation behavior ('longer inputs are truncated and flagged'), which is not stated in the schema and adds meaningful parameter-related 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 opens with 'Semantic search INSIDE a fetched record,' clearly stating the verb (search), resource (a fetched record), and scope (inside, not external). It distinguishes from sibling search tools by emphasizing 'pass the text you already pulled' and 'returns only the passages that matter,' making its purpose unmistakable.

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

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

Explicitly provides when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also describes a complementary workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'), giving clear usage context and even naming a related sibling tool.

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

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

The description adds substantial behavioral context beyond annotations: requires a Pipeworx OAuth account, phone must be verified, SMS has a 10/day cap, webhooks are auto-disabled after 10 consecutive failures, and the webhook signing secret is returned only once. This goes well beyond the readOnly/destructive/idempotent hints and fully informs the agent of side effects and constraints.

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 and front-loaded with the core purpose, then enumerates types and delivery options. While long, the complexity of the tool (5 subscription types, 3 delivery channels, account requirements) justifies the length. A more structured list format would improve scannability, but every sentence adds necessary detail.

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

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

With no output schema, the description compensates by stating the return value (subscription id) and webhook secret behavior. It covers prerequisites, type-specific parameter shapes, delivery channel options, limits, and verification steps. For a tool with nested objects and multiple variants, this is complete enough for an agent to select and invoke it correctly.

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

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

The input schema has 100% coverage, but the description significantly enhances parameter understanding by providing concrete examples for each subscription type (e.g., sec_8k items:["5.02"], polymarket_edge params:{topic:"fed"}, fred_series series_id:"UNRATE"). It also clarifies delivery channel requirements, including E.164 format, verified phone, and webhook HMAC signing details, making the schema far more actionable.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value ('Returns the new subscription id'). It clearly distinguishes this tool from siblings like list_subscriptions and unsubscribe by focusing on creation and listing supported types.

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

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

The description provides clear context for when to use the tool and details the subscription types and delivery channels. It does not explicitly name alternative tools (e.g., recent_alerts, list_subscriptions, unsubscribe) or state when not to use it, but the supported types and prerequisites (OAuth account, verified phone) give strong situational guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral context about the output: category-bucketed example questions, the fact they come from a live catalog of thousands of tools, and that passing `topic` filters the spread. This is valuable 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 longer than average, but it is front-loaded with example queries and structured with a clear purpose statement, return-behavior details, and usage guidance. Every sentence adds value; the length is justified by the tool's onboarding role. A tighter sentence on the return format would push it to 5.

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

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

With no output schema, the description fully compensates by explaining the return structure: category-bucketed example questions, each with the exact tool + argument shape. It also covers both call patterns (no args vs. with `topic`), mentions the source (live catalog), and provides examples. This is complete for an agent to use 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% (only `topic` with a description), so baseline is 3. The description adds meaning by giving concrete example values ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread. This exceeds the schema's simple enum-like hints.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape needed to answer it. It distinguishes itself from siblings by framing itself as the 'FIRST' step for learning Pipeworx capabilities, which is distinct from discover_tools and ask_pipeworx.

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

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

The description explicitly says to use this tool FIRST when you do not know what Pipeworx can do, and mentions it helps learn how to call meta-tools. While it doesn't explicitly name alternatives, the context (onboarding vs. specific queries) provides clear guidance. It could be stronger by directly excluding discover_tools but is still above average.

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=false, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral details beyond these: ownership enforcement (you can only cancel your own subscriptions) and the soft-delete behavior with retention of historical events. These are significant side effects and permission requirements that the annotations do not fully convey. 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 three concise sentences, each earning its place: the core action ('Cancel a subscription by id'), a critical authorization constraint ('Ownership is enforced'), and a side-effect clarification (deactivation vs deletion, with reference to recent_alerts). No redundancy or filler words.

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

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

For a tool with one required parameter, strong annotations (idempotent, non-destructive), and no output schema, the description is sufficient. It covers the action, permission model, and post-call impact on data availability. There is no missing information that would hinder an agent from using the tool correctly.

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

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

The input schema already provides a full description for the 'id' parameter (subscription id returned by subscribe), so schema coverage is 100%. The description mentions 'by id' but adds no new parameter-level details, such as format, validation, or examples. The ownership enforcement is a behavioral constraint, not additional parameter semantics. Thus, baseline of 3 is appropriate.

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

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

The description states a specific verb ('Cancel') and resource ('subscription by id'), making the tool's purpose unambiguous. It clearly distinguishes itself from sibling tools like subscribe (which creates) and list_subscriptions (which lists) by focusing on the cancellation action and its ownership constraint.

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

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

The description provides clear context by explaining that cancellation deactivates rather than deletes, and that historical events remain accessible via recent_alerts. This helps the agent understand when to use this tool (when you want to stop alerts but preserve history). However, it does not explicitly name alternative tools for opposite actions or edge cases, so it stops short of a full 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds rich behavioral context: the structured SEC EDGAR fast path for financial claims, fallback to grounded pipeline for other claims, and the exact set of verdicts returned. This exceeds what annotations convey.

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

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

The description is longer than average, but every sentence serves a purpose: trigger phrases, use-case, routing logic, output summary, and efficiency claim. It is front-loaded and effectively structured for a complex tool, though slightly verbose.

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

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

Given the tool's complexity and the absence of an output schema, the description adequately explains the return values (verdict, value with citation, reasoning), the routing behavior, and the decision logic. It provides enough context for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents both parameters, including examples and tolerance_pct semantics. The main description adds no additional parameter detail, so a 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?

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources. It provides multiple trigger phrases and explicitly differentiates from general lookup tools by describing the verification pipeline and verdict output.

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

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

The description explicitly says to use this tool whenever the agent needs to check factual correctness, and it distinguishes between company-financial claims and other claims with routing details. It does not explicitly state when not to use it or name alternative tools, but the guidance is clear.

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