Arcgis Brampton

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: probing multiple models, default model free, Anthropic requires own key (cost implication), and passing _apiKey straight through to api.anthropic.com. It could mention rate limits or failure modes, but overall adds significant transparency.

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

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

The description is three sentences with zero wasted words. It front-loads the core purpose, then explains the model options and API key, and ends with return format and use cases. Every sentence earns its place, making it highly efficient for agent consumption.

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 covers return format (per-model {score, confidence, signals, raw_response} + combined view). It also explains cost implications, default behavior, and optional parameters. This is complete enough for an agent to understand what the tool does and how to 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 descriptions for all 4 parameters. The description adds value beyond schema by stating the default model (Workers AI Llama-3.3-70b), clarifying _apiKey is only needed for anthropic, and explaining context helps disambiguate. This reduces ambiguity for agents selecting parameter values.

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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It distinguishes itself from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on multi-model visibility scoring, making its purpose unique and specific.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and the optional API key for Anthropic. However, it does not explicitly state when not to use this tool versus alternatives, leaving some ambiguity 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns structured answer with stable citation URIs, routes to correct tool among 4,552, works on every tier, one fast call. No contradictions.

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

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

Description is front-loaded with key guidance, uses bullet points and examples effectively. Slightly long but every sentence adds value. Structure is logical: recommendation, explanation, examples, escalation.

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

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

Given the tool's complexity (routing to 4,552 tools), the description covers purpose, usage, examples, and return format (structured answer with citation URIs). No output schema, but return type is sufficiently described.

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 6 parameters (5 aliases + question) described in detail. Description adds no further semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions using authoritative structured data from thousands of sources, with specific verb 'ask' and resource 'Pipeworx'. It distinguishes from siblings like web search, ask_pipeworx_grounded, and deep_research by prescribing when to use each.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use this tool, when to step up to grounded or deep_research, and example query types. Includes both inclusion and exclusion criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: it extracts answer only from tool result, returns explicit refusal reasons, and costs an extra LLM call. 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 relatively lengthy but efficient, with each sentence serving a purpose (purpose, behavior, usage, cost). It is well-structured and front-loaded with the key purpose. Slightly verbose in listing refusal reasons but still clear.

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

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

With 6 parameters (all aliases) and no output schema, the description comprehensively explains the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and possible failure modes. It fully compensates for the missing output schema and provides complete context for using the tool.

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

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

Schema description coverage is 100%, with all 6 parameters documented. The description only mentions 'your question in natural language' and lists aliases, which is partially redundant with the schema's property descriptions. It adds minimal additional meaning beyond what the schema provides.

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

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

The description explicitly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from the sibling 'ask_pipeworx' by describing the grounded extraction process. It clearly communicates the tool's specific purpose and differentiates it from similar tools.

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

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

The description provides clear guidance on when to use this tool (high-stakes reads, quotes, citations, financial/legal/medical) and when not to (prefer ask_pipeworx for casual lookups). It explicitly states the use case and exclusion, helping agents choose correctly.

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 mark it as readOnly, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic, response shapes, resolver confidence, parent event extraction, news fallback handling, safety mechanisms for low-confidence matches and closed/inactive markets, spread liquidity warnings, and resolution-rule risk analysis. No contradictions.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). Every sentence adds necessary detail; no fluff. Slightly verbose but justified by information density.

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

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

With no output schema, the description fully explains the return structure (result.market, result.analysis, result.evidence, resolver fields, parent_event, news fields). It covers edge cases (low confidence, closed markets, wide spreads, cancellation rules) and provides comprehensive guidance for agents to 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%. The description adds value by explaining market parameter input types (slug, URL, question text), depth parameter (quick vs thorough), and include_raw trade-offs (summarized vs full payloads). This exceeds the baseline of 3.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, resolving the market, classifying, and fanning out to data packs. It specifies inputs and outputs, and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research of specific bets.

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

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

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While not exhaustive, it provides clear context for when to invoke this tool over others.

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

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

The description discloses important behavioral traits beyond annotations: it pulls latest 10-K data with fiscal year handling, sorts results by primary metric, and returns citation URIs. It also notes efficiency gains, aligning with readOnlyHint and idempotentHint annotations. No contradictions.

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

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

The description is well-structured with trigger phrases first, then functionality and details. It is slightly verbose but every sentence adds significant value, making it clear and actionable.

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

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

Given no output schema, the description adequately explains return values (paired data and citation URIs). It covers purpose, behavior, parameter semantics, and usage scenarios comprehensively for a comparison tool with two parameters.

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

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

Despite 100% schema coverage, the description adds critical details: for type='company' it specifies financial metrics and fiscal year handling; for type='drug' it lists FAERS, FDA approvals, and trial counts. This greatly enriches parameter understanding beyond the enum descriptions.

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

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

The description explicitly states it performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with specific data sources. It clearly distinguishes from siblings like entity_profile by emphasizing efficiency and parallel execution.

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 strongly recommends this tool over sequential lookups when comparing entities, providing high-level usage guidance. However, it does not explicitly mention when not to use (e.g., for single entities), though this is implied by the sibling context.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds significant context: account required, paid plan for 'thorough' depth, expected 15-60s response time, return format with gaps[] and citations, and that it never invents evidence. 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 lengthy (multiple paragraphs) but front-loaded with critical account requirements. While comprehensive, it could be more concise without losing key details. Given the tool's complexity, it's acceptable but not optimally concise.

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

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

Despite no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, fetched_at, stable citation, and explicit gaps[]). It covers behavioral traits, usage guidelines, limitations, and alternatives, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, with parameters well-described in the schema (question, depth with enum). The description reinforces the purpose and adds minor context about depth options (quick=3, etc.), but does not significantly add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, decomposing questions into facets, parallel routing, and returning a findings packet. It distinguishes itself from sibling tools like ask_pipeworx and explicitly notes what it is not (open-web search).

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

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

Provides explicit guidance on when to use (broad/multi-part structured data questions) and when not to (breaking news, current news), along with alternatives (ask_pipeworx). Also mentions account requirements and paid plan limitations.

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 behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed'. It does not contradict annotations.

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

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

The description is front-loaded with the main purpose. However, the lengthy list of domains (SEC filings, FDA drugs, etc.) makes it somewhat verbose. While informative, a more concise list or grouping could improve conciseness.

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

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

Given the tool's 6 parameters (100% schema coverage), no output schema, and no nested objects, the description adequately explains what the tool returns and its use case. It covers the essential points for an agent to decide when to call it.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides natural language usage hints and examples for the query parameter, which adds some value, but it largely repeats what the schema already states (aliases and descriptions).

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

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

The description uses specific verbs ('Find tools by describing the data or task') and lists many concrete domains (SEC filings, FDA drugs, etc.), making the tool's purpose clear. It also distinguishes from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set'.

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 this tool ('when you need to browse, search, look up, or discover what tools exist') and when to call it first ('Call this FIRST when you have many tools available'). It does not explicitly state when not to use it, but the guidance is clear enough.

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

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

Adds behavioral details beyond annotations: fan-out across multiple sources, specific return fields, patent sunset and news fallback, parallel call. Annotations already cover safety and idempotency, so extra context is valuable but not exhaustive.

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 information-dense but well-structured with examples upfront. Could be slightly more concise, but every sentence adds value without redundancy.

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

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

Given no output schema, description comprehensively explains return data (CIK, filings, fundamentals, patents, news, LEI) including fallbacks and limitations. Fully meets completeness for a complex tool.

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

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

Schema coverage is 100% with descriptions. Description adds examples and reiterates constraints (names not supported), enhancing understanding but not surpassing schema.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company, with examples of user queries. It distinguishes itself from sibling tools like resolve_entity by specifying when to use each.

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

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

Explicitly says to prefer this tool over chaining individual lookups for holistic views, and states that names are not supported—use resolve_entity instead. Includes when-to-use and alternative.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's mention of 'delete' aligns. It adds context about clearing sensitive data but does not reveal additional behavioral traits 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?

Two sentences, zero wasted words, front-loads the core action, and provides usage guidance succinctly. Excellent structure.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage scenarios, and pairing with siblings. Nothing is missing given the tool's simplicity.

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

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

Schema coverage is 100% with a clear description for 'key'. The description reiterates 'by key' without adding new meaning or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by pairing mention, making its specific function unambiguous.

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

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

Provides explicit when-to-use scenarios: context is stale, task done, or clearing sensitive data. Mentions pairing with remember and recall. Lacks explicit when-not-to-use but context is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds context about fetching pages and extracting content, which aligns with these hints. It doesn't contradict annotations and provides useful behavioral detail.

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

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

The description is concise: two sentences for the core action and one sentence for use cases. It front-loads the primary function and avoids unnecessary detail, making it efficient.

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

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

Given rich annotations and full schema coverage, the description adequately explains the output format (llms.txt markdown blob) and use cases. No missing information for effective tool usage.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description adds minimal extra meaning beyond the schema, 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 generates an llms.txt file for a URL, specifying its use for AI crawlers like ChatGPT, Claude, and Perplexity. It details the action (fetch, extract, emit) and output format, distinguishing it from siblings through specific functionality.

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: getting a client's site indexed, drafting for own project, or auditing competitor AI presence. While it doesn't cover when not to use it, the guidelines are clear and helpful.

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, providing a strong safety profile. The description adds specific context about what the schema includes (fields, geometry type, record count, capabilities), 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?

A single, concise sentence that front-loads the tool's purpose and enumerates the return details. Every word is meaningful with no redundancy.

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

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

Given the tool has one parameter, no output schema, and the description fully covers what the tool returns (fields, geometry type, record count, capabilities), it is complete for its simplicity.

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

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

Schema coverage is 100%, and the description adds an example URL format (e.g., '.../FeatureServer/0'), which adds value beyond the parameter's description alone.

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

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

The description clearly states the verb 'get', the specific resource 'ArcGIS Feature/Map Service layer's schema', and lists the returned components (fields, geometry type, record count, capabilities). This differentiates it from siblings like 'query_layer', which is for data queries.

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

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

The description implies usage via url but does not explicitly state when to use this tool versus alternatives (e.g., 'query_layer'). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, indicating safe, idempotent read operation. The description adds value by listing the exact fields returned ('id, type, params, created_at, last_fired_at, fire_count'), providing useful behavioral detail beyond annotations.

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

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

Two sentences, front-loaded with purpose and output, then usage guidance. No wasted words. 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?

For a simple zero-required-param tool with no output schema, the description covers purpose, return fields, and usage guidance. It is fully sufficient given the tool's low complexity and rich 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?

Schema coverage is 100% for the single parameter (include_inactive). The description does not add any additional meaning beyond what the schema already provides. Baseline 3 is appropriate when schema covers parameters fully.

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 'List the caller's active subscriptions.' This is a specific verb+resource+scope, and it naturally distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use context and practical motivation.

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

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

The description discloses behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. Annotations are all false; description adds useful context without contradiction.

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

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

The description is a single paragraph but well-structured: starts with purpose, lists use cases, then specific instructions and constraints. It is efficient but could be more concise with bullet points. No wasted sentences.

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

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

The description covers the tool's purpose, usage guidance, and behavioral constraints. There is no output schema, but for a simple feedback tool the description is sufficiently complete. The nested context object is explained. Minor gap: no mention of return value.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining each type in detail and providing guidance for the message field (be specific, 1-2 sentences). The context object is also explained, adding value beyond the schema.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise) and explaining each. It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback submission.

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

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

The description provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and what not to do (avoid pasting end-user prompt). It also mentions rate limits and quota. However, it does not explicitly contrast with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as safe. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradiction.

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

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

Five sentences efficiently packed: main action, return values, three use cases, then data source and caching. No wasted words. Front-loaded with the core purpose.

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

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

For a simple one-parameter tool with good annotations, the description is complete. It explains what is returned, use cases, data provenance, and caching. No output schema needed as return values are described.

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 parameter fully (100% coverage with enum and description). Description adds meaning by explaining how window choice affects results (short windows for hot, long for steady-state). Baseline 3 plus extra context justifies 4.

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

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

The description clearly states the tool returns trending data from Pipeworx: top tools, packs, and call volume over a window. This distinguishes it from siblings like ask_pipeworx (for asking questions) and discover_tools (for discovering tools). Verb 'Returns' plus specific resource makes 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool before asking, aligning use case). While no when-not or alternatives are mentioned, the guidance effectively indicates when to use the tool. Sibling differentiation is implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint etc. Description adds rich behavioral details: semantic anchor with Jaccard similarity, partition filter, fill check against live CLOB depth, and output structure. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with main purpose. Every sentence adds value, though could be slightly more concise. Organized logically from overview to detailed mode explanations.

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

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

Given no output schema, the description thoroughly explains the response format and fill check. Covers multiple modes, algorithms, and edge cases (placeholders, similarity). References sibling tools appropriately.

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 description adds significant extra context: example slugs, that URLs are accepted, how each parameter affects behavior, and the difference between event and topic modes.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) and differentiates from siblings like polymarket_fill_risk.

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

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

Explicitly states when to use each mode (no args for trending, event for specific market, topic for cross-event) and provides recommendations. Also warns when not to trade (realizable_edge_pp ≤ 0) and references sibling for custom sizing.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context beyond annotations, including that results are cached at the KV level for 1 hour, the three response segments (model_driven, structural_arbitrage, concentrated_longshot), and diagnostic information for empty segments.

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 verbose and dense with technical detail about model families and edge calculations. While well-structured with sections, it could be more concise without losing key information. The length may overwhelm agents, but it is comprehensive.

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

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

Despite no output schema, the description thoroughly explains the response structure including top-level segments, fed_candidates, and _diagnostics. It also details fields like edge_pp_net, kelly_fraction, and 24h-move warning. Given 9 parameters and complex output, the description is complete.

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

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

All 9 parameters are documented in the schema. The description adds value by providing rationale and usage tips, such as the explanation for slippage_pp ('Polymarket has zero trading fees...but bid/ask + thin depth typically eats 20-50bp per trade') and the note on min_partition_leg_kelly for filtering thin partitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on opportunity discovery across multiple model families.

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

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

The description provides explicit guidance on when to use the tool (discovering betting opportunities) and includes tradeable-edge knobs (min_liquidity, max_spread_pp) for filtering. It also explains that Fed bets are excluded from ranking. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: history bounded by 60-day TTL, decay from daily closes, snapshot gaps due to cache misses, and detailed response structure. No contradiction.

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

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

The description is detailed and well-structured, starting with purpose, then response breakdown, then limitations. It is front-loaded but somewhat verbose; each sentence adds value, but could be tightened slightly.

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

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

Despite no output schema, the description fully explains the response structure: tracked[], expired[], snapshot_dates[]. It covers limitations, edge cases, and the meaning of fields. For a complex tool, this is comprehensive.

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

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

Schema coverage is 100%, but the description adds meaning: explains 'days' as lookback with default/max, 'window' as snapshot family with default. It also clarifies the effect of these parameters on the response, going beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings like polymarket_edges by focusing on time-series and decay analysis, providing a specific verb+resource combination.

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

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

The description provides context on when to use (e.g., differentiating fresh vs old edges) and lists limitations like the 60-day TTL. However, it does not explicitly state when not to use or compare to other tools, but the purpose is sufficiently distinct.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral details: walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and warns about thin legs and forced directional risk. No contradictions.

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

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

Well-structured with clear sections for single-market and basket modes. Every sentence adds meaningful information; however, could be slightly more concise given 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?

No output schema, but description fully enumerates return fields for both modes, including verdicts, capture ratios, and risk indicators. Covers edge cases (thin books, partial fills) and provides complete behavioral context for a complex tool.

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

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

Schema covers all 4 parameters with descriptions. Description adds value: default values, mode-specific behavior for side and size_usd, clamp range for size_usd, and the auto-default for basket side. This exceeds the baseline of 3 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?

States specific purpose: realizable vs. theoretical edge check using live CLOB order-book depth. Clearly distinguishes two modes (single-market and basket) and provides distinct behaviors for each.

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

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

Explicitly advises use before acting on polymarket_arbitrage signals or trades above ~$500. Warns against partial fills leading to directional risk, the dominant loss mode in real arb-bot P&L.

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 safe read-only behavior. The description adds rich behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped counters) that explain edge cases when spreads are not meaningful. It also clarifies that the tool indicates when bet shapes are equivalent or not.

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?

Structured with clear sections (modes, response, safety fields) and no filler. Every sentence provides essential information. Front-loaded with the core purpose.

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

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

Given no output schema, the description sufficiently explains the response format (leg-by-leg prices, matched spreads, safety fields). It covers all aspects needed for correct invocation and result interpretation, including edge cases.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the interplay between 'topic' and the explicit parameters, and lists the 10 pre-mapped shortcuts. This goes slightly beyond the schema's basic type/description.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings (e.g., polymarket_arbitrage) by focusing on two-venue comparison, not single-venue arbitrage. The two modes and response structure are explicitly detailed.

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 describes two usage modes (topic shortcuts vs. explicit tickers) and provides a strong caution that pre-mapped topics often return compatibility warnings, guiding agents to expect limited tradeable spreads. This helps the agent decide when to use the tool and when results may be meaningless.

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, idempotent, non-destructive behavior. The description adds details on SQL-like query capabilities, pagination, and return of attributes/geometry, which augments the annotation signals 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 extremely concise: one sentence with an example. It front-loads the purpose and immediately provides actionable guidance. Every word is essential.

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 query tool with 6 parameters and no output schema, the description mentions return value (attributes and geometry), covers all key aspects like pagination, and includes a sampling pattern. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by providing usage examples (e.g., 'where="1=1"' and 'out_fields="*"') and clarifying the SQL-like nature, which goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. It references 'from search_datasets', tying it to its sibling for discovering layers, and distinguishes from other tools like layer_info.

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 usage context via the sampling example and ties to search_datasets. It doesn't explicitly list when not to use or alternatives, but the sibling context and example are sufficient for 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 indicate readOnly, idempotent, and non-destructive. The description adds value by explaining key retrieval vs list-all behavior and scoping, 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?

Two sentences with no redundancy. Each sentence serves a clear purpose: core function and usage context.

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 param and strong annotations, the description fully covers retrieval, listing, scoping, and pairing, leaving no gaps.

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

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

Schema coverage is 100% with clear parameter description. The description reinforces the schema but doesn't add significant semantic value beyond it.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys when omitted, with a specific verb and resource. It distinguishes from siblings 'remember' and 'forget'.

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

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

Provides explicit guidance on when to use (look up stored context) and how to pair with 'remember' and 'forget'. Also notes scoping by user identifier.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds value by explaining that mark_read flags events as read, affecting subsequent calls, and that the feed is persisted. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, then key data fields, filtering options, and usage guidance. No redundant information; every sentence adds value.

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

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

Given no output schema, the description adequately covers return fields (source, citation_uri, raw payload) and usage patterns (polls, alternative API). It explains mark_read behavior but does not explicitly mention pagination or the limit parameter's effect, though schema covers it.

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

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

Schema covers all 5 parameters with descriptions. The tool description adds context on filtering by type and since, and the effect of mark_read, enriching schema details. It does not compensate for any gaps since coverage is 100%.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the verb 'pull' and resource. It distinguishes from siblings like 'list_subscriptions' and 'subscribe' by focusing on recent alerts from a persisted feed.

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

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

Provides guidance on when to use the tool ('polls work fine') and mentions an alternative for scripts/dashboards via a direct API URL. However, it does not explicitly state when not to use this tool compared to 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: it fans out to multiple APIs, explains fallback (GDELT preferred, GNews on rate limits or 5xx), notes a pending API sunset (PatentsView May 2025), and describes the return structure (changes[], total_changes, pipeworx:// URIs). This goes well beyond what annotations alone 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 single paragraph but uses front-loaded query examples to orient the agent immediately. Every sentence earns its place—no filler. It could be slightly more structured (e.g., bullet points for sources/parameters), but it remains concise at ~100 words for 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 the tool has no output schema, the description fully explains the return structure (changes grouped by source + total_changes count + citation URIs). It covers all key behaviors: multi-source fan-out, fallback logic, parameter behavior, and soft-failures. For a tool with 3 required parameters and complex orchestration, this is comprehensive.

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 3 parameters described in schema). The description adds value by explaining the `since` parameter format with examples ('2026-04-01', '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for monitoring. For `value`, it clarifies ticker vs CIK with examples. This adds usability beyond the schema, though not extensive.

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 starts with multiple real-world query examples ('What's new with X', 'latest on Y'), then states the core function: change feed for a company in a given window via one parallel call. It names specific sources (SEC, GDELT, GNews, USPTO) and distinguishes from the sibling 'entity_profile' tool, which is for static profiles. This provides a specific verb (fetch changes) and resource (company), with clear differentiation.

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 when to use this tool (for recent changes/news) and when not: 'Use entity_profile instead when you want the static profile'. It also provides guidance on parameter values (e.g., 'Use "30d" or "1m" for typical monitoring') and notes fallback logic (GDELT→GNews) and soft-fail (USPTO). This gives an agent clear context for selection.

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

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

Annotations indicate write operation (not read-only), idempotent, not destructive. The description adds critical behavioral context: key-value pairs are scoped by the agent's identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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 concise: two sentences that front-load the purpose, then provide usage guidance, storage details, and related tools. Every sentence earns its place with no redundancy or wasted words.

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

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

Given no output schema, the description does not mention the return value, which is a minor gap. However, it covers scope, retention, and interaction with recall/forget, making it fairly complete for a simple key-value store. The idempotent behavior is hinted but not explicitly stated.

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

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

Schema has 100% description coverage, so the schema already documents both parameters. The description adds value by providing naming conventions for keys (e.g., 'subject_property') and clarifying that values can be any text, which goes beyond the schema's generic 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 purpose: save data for later reuse across conversations or sessions. It provides concrete examples (resolved ticker, target address, user preference) and contrasts with sibling tools recall and forget, establishing clear differentiation.

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 guides when to use the tool: 'when you discover something worth carrying forward so you don't have to look it up again.' It also mentions pairing with recall and forget. However, it does not explicitly state when not to use it or provide alternatives beyond these 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups', revealing internal complexity and efficiency gains 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 well-structured, starting with example user queries, then stating the primary use case, and detailing supported types. Every sentence adds useful information. It is slightly verbose but packs a lot of value without redundancy. Could be marginally shorter.

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 explicitly lists what is returned for each type (ticker, CIK, citation URI for company; RxCUI, ingredient, brand for drug), covering return values adequately. It lacks details on error handling or edge cases, but for a lookup tool this is reasonably complete.

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

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

Schema coverage is 100% with both parameters described. The description enriches meaning by specifying exact return fields for each type (e.g., 'ticker + 10-digit CIK + company_name' for company, 'RxCUI + ingredient + brand' for drug) and providing input examples (e.g., 'AAPL', '0000320193', 'ozempic'), adding significant value beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples ('What's the ticker for…' / 'find the CIK for…'). It lists supported entity types (company, drug) and explicitly says 'Use FIRST whenever you have a name but need an ID', distinguishing it from siblings that operate on already-resolved IDs.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID'. It also details when to use each type (company vs drug). However, it does not explicitly state when not to use this tool or mention alternatives among siblings, though the 'first' directive strongly implies prioritization.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds detail: probes each entity with ai_visibility_check, ranks by score, surfaces extremes, and describes return format (ranked list with score, confidence, signal density). 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?

Three sentences, front-loaded with action, no waste. Each sentence provides essential info: what it does, how it works, use case, output.

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

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

Given no output schema, description returns expected output. Parameters fully covered. Use case and behavior explained. Complete for an AI agent to select and 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 covers all 4 parameters. Description adds context: entities are 2-8 with first as subject, context disambiguates common names. Adds value beyond schema by explaining usage intent.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, with ranking and identification of most/least recognized. Includes specific use case for competitive AI-marketing audits. Distinguishes from sibling ai_visibility_check which is for single entities.

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

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

Provides clear context: comparing multiple entities for competitive audits. However, lacks explicit when-not-to-use or alternatives. Implicitly suggests use when comparing multiple entities vs ai_visibility_check for single.

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

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

The description discloses composite behavior (fanning out across two services), partial failure handling ('sources_failed will list it'), and a performance caveat ('bundlephobia's first measurement... can take 5-30s'). These details go beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and add valuable behavioral context.

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

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

The description is a single dense paragraph that front-loads the main purpose and then provides detailed listing of return fields and behavior. While every sentence adds value, the structure could be improved with bullet points or clearer separation of sections for easier scanning. Still, it is concise relative to the information conveyed.

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

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

Given the tool's complexity (two external services, composite check, no output schema), the description thoroughly covers the return structure listing all fields (e.g., is_latest, license, advisory_count, bundle_kb_gz, etc.), partial failure, and alternative version list. It provides sufficient context for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with clear parameter descriptions (package name with scope support, version defaults to latest). The description adds context about the composite check but does not significantly enhance parameter meaning beyond the schema. 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 as a composite check for evaluating npm packages before adding to a project. It explicitly mentions the data sources (deps.dev and bundlephobia) and the types of checks (license, advisories, version history, bundle size). The purpose is specific and distinguishes from sibling tools, which cover different domains.

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 guidance: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also notes the ecosystem limitation (NPM only in v1) and directs to 'deps.dev:version directly' for other ecosystems, helping the agent know when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return structure and a workflow hint, but does not disclose additional behavioral traits like rate limits or result limits beyond the 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 two sentences, no wasted words, and front-loads the purpose. Every sentence is necessary.

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

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

The description explains what the tool returns and how to use the output with other tools. With no output schema, it compensates well. However, it could mention pagination or result count behavior, but overall it is sufficiently complete for a search tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add significant meaning beyond the schema's parameter descriptions.

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

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

The description specifies a specific verb ('Search'), resource ('City of Brampton GIS open geospatial datasets'), and what it returns (name, summary, record_count, owner/org, feature service url). It explicitly distinguishes from siblings by mentioning that the returned url should be passed to 'query_layer' or 'layer_info'.

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

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

The description clearly states to search by keyword and indicates the return value. It implies a workflow (search then use url in other tools), but does not explicitly state when to use this tool vs alternatives or provide exclusions.

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

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

Adds significant value beyond annotations: details embedding model (BGE-base-en), similarity measure (cosine), window size (500-char), and truncation behavior (200K cap with flag). 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?

Two clear, purpose-driven sentences followed by a dense technical sentence. Front-loaded with usage context. Dense third sentence earns its place but could be slightly restructured for clarity.

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, but description adequately hints at return format (passages with offsets and similarity scores). Covers truncation, pairing, and technical details, making it complete for a retrieval tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds natural-language query examples and clarifies 'text' as document text and 'limit' as max passages, enriching 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?

Describes semantic search inside a fetched record with specific verb 'search within' and resource reference. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and use case for oversized records.

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 (when record is too large for prompt) and pairs with ask_pipeworx_grounded. Also discloses cap and truncation behavior, providing clear boundary conditions.

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 behavioral context beyond annotations: it confirms creation of a subscription (matching readOnlyHint=false), explains authentication requirements, details delivery method limitations (SMS cap, webhook auto-disable), and notes the return value. It does not fully explain idempotency behavior (despite idempotentHint=true) but overall provides adequate transparency.

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

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

The description is front-loaded with the core purpose and progressively adds details. Every sentence contributes meaning. It is slightly long but well-organized. Minor redundancy exists (e.g., mentioning feed delivery both in description and in delivery section), but overall it is efficient for the information conveyed.

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

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

Given the complexity (nested objects, multiple types, no output schema), the description covers input details thoroughly and explains the output minimally but adequately ('Returns the new subscription id'). It omits details on idempotency and error handling, but these are partially covered by annotations and the schema. For a creation tool, it is 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?

Despite 100% schema coverage, the description adds significant value by providing concrete examples for each type and clarifying parameter structures (e.g., items codes, topic, series_id). It also explains delivery options with real-world constraints (phone verification, 10/day cap) that go 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 first sentence clearly states the verb 'Create' and resource 'proactive monitoring subscription' with a specific context 'live-data event stream'. It also explicitly states the return value. The purpose is unambiguous and distinct from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides strong usage context: required auth (Pipeworx OAuth account), supported subscription types with examples, and delivery options with constraints. It lacks explicit guidance on when not to use or direct comparisons with alternatives, but the provided information is sufficient for correct usage in most cases.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: it returns example questions with tool+argument shapes and explains the optional topic filter. No contradictions.

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

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

The description is front-loaded with trigger phrases and lists. It is slightly long but efficiently packs necessary info. Could be slightly more concise, but no wasted sentences.

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

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

Given it's an onboarding tool with one optional parameter and no output schema, the description is complete: it explains the return format (category-bucketed questions with tool shapes), when to use, and the topic parameter. Everything needed for the agent to invoke correctly.

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

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

Schema coverage is 100% (1 parameter described). The description enriches the schema by explaining the effect of omitting topic (full spread) vs. specifying a focus area, and lists the possible values with examples.

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

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

The description clearly states the verb ('returns category-bucketed example questions') and the resource (live catalog of tools). It distinguishes itself from siblings by being the onboarding entry point, using trigger phrases like 'getting started' and 'use this FIRST'.

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 specifies when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also implies alternatives (e.g., after learning, use specific tools like ask_pipeworx).

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds critical context: ownership enforcement and that the row is deactivated (not deleted) preserving historical events, going 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?

Two sentences, no extra words, front-loaded with the action. Every sentence adds value with zero waste.

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

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

For a tool with one parameter and no output schema, the description fully covers the behavior (ownership, deactivation) and result (historical events available via recent_alerts), making it complete for its complexity.

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

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

Schema coverage is 100% for the single 'id' parameter, so baseline is 3. The description does not add further semantic details about the parameter beyond what the schema already provides.

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

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

The description 'Cancel a subscription by id' uses a specific verb-resource pair and clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing clear context for when to use this tool versus other subscription-related 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 indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds that it returns a verdict with structured data and citation, and replaces multiple sequential calls. It does not contradict annotations and provides useful behavioral context beyond the annotations.

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

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

The description is well-structured, front-loading example intents, then stating when to use, supported domain, return values, and efficiency. While slightly verbose, each sentence adds value. Could be tightened without losing information.

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

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

Given no output schema, the description sufficiently enumerates return fields (verdict, structured form, actual value, citation, percent delta). It covers supported scope and usage rationale. Missing explicit error handling or out-of-scope behavior, but overall complete for the tool's simplicity.

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

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

The sole parameter 'claim' has a schema description with examples, achieving 100% coverage. The tool description adds the semantic constraint that claims should be company-financial, which provides additional guidance beyond the 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 clearly identifies the tool's purpose: verifying natural-language factual claims against authoritative sources, with specific examples of user intents. It also mentions the supported domain (company-financial claims) and distinguishes it from sequential multi-step alternatives.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and notes its current limitation to company-financial claims. It implies not for other claims but does not explicitly list exclusions or alternative tools.

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