Arcgis Peachtreecorners

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: default model, API key requirement for Anthropic, and return format (per-model details + combined view), which enhances transparency 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?

The description is concise (4 sentences) and front-loaded with the main purpose, followed by details on defaults, return format, and use cases. Every sentence adds value without repetition.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description adequately covers the return format and use cases. It lacks details on error handling or rate limits, but these are not critical for a probe tool with strong annotations.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema by explaining the default model (Workers AI Llama-3.3-70b) and that the API key is passed straight through to Anthropic, plus examples for the entity parameter.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it (0-100), using specific verbs and resources. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which may have overlapping 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?

Provides clear use cases such as AI-marketing audits, pre-launch brand checks, and competitive monitoring, but does not mention when not to use it or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds useful behavioral context: it routes to 4774 tools, returns structured answer with citation URIs, works on every tier, and is one fast call. No contradictions. The description adds value beyond annotations.

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

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

The description is long (over 400 words) but well-structured, starting with preference over web search, then use cases, examples, and alternative guidance. However, it could be more concise without losing key 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 the tool's complexity (4774 tools, many sources), the description is comprehensive: it covers input, behavior, output structure, and alternatives. No output schema exists, but the description mentions 'structured answer with stable pipeworx:// citation URIs', which is sufficient for an agent to understand the 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% with one required parameter 'question' and aliases documented. The description provides examples and explains it accepts natural language, which adds meaning beyond the schema. This justifies a 4 rather than baseline 3.

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

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

The description clearly states the tool answers factual questions using authoritative structured data with citations, and routes to many tools. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the purpose specific and clear.

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 over web search, provides examples of when to use (factual queries), and gives guidance on when to step up to alternatives (ask_pipeworx_grounded, deep_research). This is comprehensive and actionable.

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 extracts only from tool result, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and mentions cost trade-off. 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 a single paragraph but contains all necessary information. It could be more structured (e.g., bullet points for refusal reasons), but every sentence is useful and not redundant.

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

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

Given the tool's complexity (grounded query with refusal handling) and lack of output schema, the description provides sufficient behavioral details, return format, and usage guidance. It covers what the agent needs to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions, including aliases. The description adds no new parameter guidance. Agent can understand parameters from schema alone; description does not improve clarity beyond schema.

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

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

The description clearly states this is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded extraction and refusal on missing data.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and gives examples like financial, legal, medical. Also advises preferring 'ask_pipeworx' for casual lookups due to extra cost.

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

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

The description extensively details behavior beyond annotations: classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits, illiquidity notes, and cancellation rule parsing. Annotations indicate read-only, idempotent, etc., and description aligns 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 verbose (multiple paragraphs) but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It front-loads the main purpose but could be more concise. Still readable and informative.

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 and moderate complexity, the description covers inputs, processing, edge cases (low-confidence, closed markets, wide spreads, cancellation rules), and structured response fields. It is thorough and leaves few 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?

With 100% schema description coverage, the description still adds significant value: e.g., explains depth levels ('quick = 2-3 evidence sources'), include_raw trade-offs (response size), and market input flexibility. It goes beyond the schema's brief 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). This clearly distinguishes it from siblings like polymarket_edges and validate_claim.

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

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

The description gives explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies when not to use by differentiation from other tools, but does not provide explicit 'when not to use'. Still 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?

Discloses many behavioral details beyond the readOnlyHint, openWorldHint, and idempotentHint annotations: explains how fiscal years are handled (e.g., AAPL Sep, NVDA Jan), that results are sorted by primary metric, and that citation URIs are returned. 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?

Description is thorough but somewhat lengthy; however, every sentence adds value. Front-loaded with example queries for quick recognition. No redundant information. A slightly tighter structure would not harm, but current form is acceptable.

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

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

Given the tool's moderate complexity (two simple parameters, no output schema), the description covers input format, behavior, output structure (paired data + citation URIs), and even edge cases (off-calendar fiscal years). It leaves no obvious gaps for an agent to misunderstand.

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

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

The description significantly enriches both parameters. For 'type', it explains the difference in data pulled for 'company' vs 'drug'. For 'values', it provides example formats (tickers/CIKs for companies, drug names) and constraints (2-5 items). This adds crucial context beyond the enum and array types in the schema.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It specifies the data sources (SEC EDGAR/XBRL for companies, FAERS/drug data) and key metrics (revenue, net income, etc.). It distinguishes itself from siblings like entity_profile by explicitly noting it replaces multiple sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries like 'compare X and Y' and 'which is bigger / better / larger'. Clearly indicates when this tool should be used (comparison tasks) and implies alternatives are single-entity lookups.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description discloses critical behavioral traits: account requirement, free vs paid tier behavior, parallel processing, response format with citations and gaps, expected latency (15-60s), and limitations for breaking news. 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 well-structured and front-loaded with the most critical information (account requirement, alternative). Every sentence adds value; there is no fluff. Despite length, it is efficiently organized for an AI agent.

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

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

Given no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, citation, gaps) and expected timing. It covers all necessary context for selection and invocation.

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

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

Schema coverage is 100%, but the description adds meaningful context: explains depth values (quick=3, standard=5, thorough=8) and ties thorough to paid plans. Also clarifies that the question parameter accepts broad/multi-part queries due to the tool's decomposition capability.

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 defines the tool as grounded multi-source research across structured data sources, distinguishing it from sibling tools like ask_pipeworx. It specifies the scope (1242 sources, parallel decomposition) and contrasts with 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?

The description explicitly states when to use (broad/multi-part questions over structured data), when not (breaking news, single lookups), and provides alternatives (ask_pipeworx). It also notes 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 provide readOnly, idempotent, non-destructive hints. Description adds that it returns top-N tools with full schemas and ready-to-call results, enhancing transparency 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 succinct sentences plus a list of domains; every part earns its place. Front-loaded with purpose and use case.

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

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

No output schema, but description fully explains what is returned (names, descriptions, schemas with examples) and when to use the tool, making it self-sufficient.

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

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

Schema covers all 6 parameters with descriptions and examples, but description adds value by listing searchable domains (e.g., SEC filings, FDA drugs) which guides query crafting.

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 'Find tools by describing the data or task', lists many specific domains, and distinguishes from sibling tools by advising to call this first 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?

Explicitly says use when browsing, searching, or discovering tools, and advises to call this first. Lacks explicit when-not-to-use instructions but contextually clear.

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

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

Adds substantial context beyond annotations: lists sources (SEC, XBRL, USPTO, news, GLEIF), describes return fields, notes USPTO sunset May 2025, and fallback behavior. No contradiction with readOnlyHint=true etc.

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

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

Description is thorough but front-loaded with examples. Every sentence adds value, though slightly verbose. Efficient for the complexity.

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

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

Given no output schema, description fully explains returned fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and constraints. Covers temporal, fallback, and input limitations.

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

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

Schema coverage is 100%; description adds meaning: value accepts ticker or zero-padded CIK, type only 'company' currently, and clarifies that names are not supported. Enhances schema info.

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

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

Description clearly states 'full cross-source profile of a US public company' with example queries. Distinguishes from sibling tool 'resolve_entity' for name input. Specific verb+resource+scope.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when holistic view needed.' Also advises using resolve_entity if only a name is available. Clear when-to-use and when-not-to.

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 destructiveHint=true and idempotentHint=true. Description confirms deletion and adds usage context but does not disclose extra behavioral traits like what happens if key is missing or whether deletion is permanent.

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

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

Three concise sentences: purpose, usage context, and sibling pairing. No wasted words, front-loaded with action.

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

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

For a simple one-parameter destructive tool with annotations and clear sibling relationships, the description covers purpose, usage, and context. Could mention return value (e.g., confirmation) but not essential.

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 description 'Memory key to delete'. Description adds no new meaning beyond 'by key', so baseline 3 is appropriate.

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

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

Description clearly states the tool deletes a memory by key, using the verb 'Delete' with specific resource 'memory' and identifier 'key'. It distinguishes from siblings 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly lists three use cases (stale context, task done, clear sensitive data) and suggests pairing with 'remember' and 'recall'. Lacks explicit when-not-to-use scenarios, but the positive guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by stating it fetches pages, extracts content, and outputs text. No contradictions; the description complements the annotations well.

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

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

The description is four sentences: first sentence states purpose, second details process, third describes output format, fourth lists use cases. It is front-loaded with the most critical information and contains no extraneous words.

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

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

Given the tool's complexity (2 parameters, no output schema), the description fully covers what the tool does, its input (URL and optional max_links), output format ('single text blob'), and use cases. No missing critical information is apparent.

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

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

Schema coverage is 100% with both parameters described. The description adds value by showing an example URL ('https://example.com') and specifying default and maximum for max_links ('default 25, max 50'), which goes beyond the schema.

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

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

The description clearly specifies the verb 'Generate' and the resource 'llms.txt file' for any URL. It explains the process (fetch, extract title/description/key links, emit standard format) and distinguishes from sibling tools like 'ai_visibility_check' by focusing on generating the file itself.

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, auditing competitor). While it lacks negative guidance or alternatives, the provided scenarios are concrete and helpful for an AI 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=true, idempotentHint=true, destructiveHint=false. The description adds what the tool returns (fields, geometry type, record count, capabilities), which is useful but does not disclose other behavioral traits like error handling or rate limits. With good annotation coverage, a 3 is appropriate.

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

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

The description is a single sentence of 24 words, with no fluff. It is front-loaded with the key action and resource.

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 no output schema, the description covers what is returned (fields, geometry type, record count, capabilities). It is complete enough for an agent to understand usage, though it could mention that it works for both Feature and Map Service layers.

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% (one parameter described). The description adds a URL example and clarifies it's a layer URL, but the schema already documents the parameter. Baseline 3 is correct.

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

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

The description clearly states the action (Get) and resource (ArcGIS Feature/Map Service layer's schema) and lists what is returned (fields, geometry type, record count, capabilities). It distinguishes from sibling tools like query_layer which query data, but does not explicitly differentiate.

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 no guidance on when to use this tool versus alternatives, such as before querying or exploring schema. No context about prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that only active subscriptions are returned by default (with option to include inactive). 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 only two sentences, front-loaded with the main action, and every sentence earns its place. No redundancy.

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

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

For a simple list tool with rich annotations and full schema coverage, the description covers purpose, return fields, usage guidance, and parameter behavior adequately. No gaps.

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

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

The only parameter 'include_inactive' is fully documented in the input schema. The description does not add additional semantics beyond the schema's description. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states 'List the caller's active subscriptions', specifying verb (list), resource (subscriptions), and scope (caller's active). It also lists returned fields, distinguishing from sibling tools 'subscribe' and 'unsubscribe'.

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

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

The description explicitly states when to use this tool: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear usage context, though it could mention scenarios where it's not appropriate.

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

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

Annotations declare readOnlyHint=false, etc., but the description adds valuable context: the tool is free, does not count against tool-call quota, is rate-limited to 5 per identifier per day, and feedback is read daily and affects the roadmap. 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 at about 5 sentences, with the core purpose and usage guidelines front-loaded. 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 the thorough schema coverage, clear usage guidelines, and behavioral transparency, the description is fully complete for an agent to invoke the tool correctly. No output schema is needed as the tool likely returns a simple acknowledgement.

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

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

The input schema has 100% parameter description coverage, and the description supplements with advice on how to write the message (e.g., not pasting user prompts). The 'type' enum is well-explained in both schema and description.

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

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

The description uses the specific verb 'Tell' and the resource 'Pipeworx team' to clearly state the tool's purpose. It explicitly lists the types of feedback (broken, missing, praise), distinguishing it from sibling tools that are query/research focused.

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: for bugs, feature requests, data gaps, or praise. It also advises on what to include ('in terms of Pipeworx tools/packs') and what to avoid (pasting end-user prompts), along with rate limit details (5 per day).

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 and idempotentHint=true, so the description adds value by disclosing the data source (CF analytics-engine), stating no PII, explaining caching (5min-1h), and describing the output shape (pack, tool, count). This goes beyond annotations without contradiction.

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

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

The description is concise and well-structured: a clear first sentence stating output, followed by a bullet list of use cases, then technical details. Every sentence contributes essential information without redundancy or extraneous content.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and the richness of annotations, the description is complete. It covers output, use cases, data source, privacy, caching, and parameter insights. No critical information is missing for an agent to use it effectively.

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

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

Schema coverage is 100% and the schema already describes the parameter well. The tool description adds meaning by explaining the trade-off between shorter and longer windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This supplements the schema's description.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over configurable windows. Three specific use cases make the purpose unmistakable. It distinguishes itself from sibling tools like 'discover_tools' by focusing on aggregate usage trends of other AI agents.

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 three explicit use-case scenarios guiding when to invoke the tool: discovering hot data sources, confirming canonical tools, and aligning use cases. While it doesn't explicitly state when not to use it, the use cases cover the common motivations. A slightly lower score would be for missing explicit alternatives or exclusions.

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

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

Beyond annotations (readOnlyHint, etc.), the description details operational traits: it walks child markets, computes partition checks, applies Jaccard similarity threshold, filters placeholder slugs, and performs fill checks against live order book depth. It warns when realizable edge is non-positive, advising not to trade. 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 comprehensive and well-structured with logical paragraphs for each mode and feature. It is slightly lengthy but every paragraph adds value, covering purpose, parameter usage, filters, response format, and fill check. A minor improvement could be to condense some technical details, but it remains effective.

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

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

Given the tool's complexity (three modes, multiple checks) and the absence of an output schema, the description covers all necessary behavioral and response details. It explains the response structure (opportunities array with gap_pp, suggested_trade, reasoning) and the fill check logic. This ensures an AI agent has sufficient context to invoke and interpret results correctly.

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

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

The description adds substantial meaning beyond the input schema. It explains that the event parameter triggers single-event mode with partition checks and monotonicity validation, while topic triggers cross-event scanning across related events. It also describes the behavior when no args are provided (trending scan). The schema only provides brief descriptions; the description enriches them significantly.

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: to find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes of operation (trending scan, event mode, topic mode) with specific guidance, making the purpose highly specific and distinct from sibling tools like polymarket_edges or polymarket_edge_tracker.

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 each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for a themed cross-event scan'. It also explains the advantage of cross-event mode and directs users to polymarket_fill_risk for custom sizing, effectively differentiating from alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, diagnostics), detailed model computations (e.g., partition_overround with per-sport α, concentrated_longshot gates), and nuances like Fed candidates being excluded due to unreliable signals.

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

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

The description is very detailed and well-structured, starting with the main purpose and progressing through model families, response structure, knobs, and diagnostics. However, it is quite lengthy and includes detailed formulas that may be unnecessary for an agent to use the tool effectively.

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

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

Given the complexity (9 parameters, no output schema), the description fully explains the output structure (by_segment, diagnostics) and caching. It covers edge cases like why segments might be empty (_diagnostics provide counters) and the exclusion of Fed bets. The description is self-contained and provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining high-level behavior (e.g., min_kelly skips small opportunities, min_partition_leg_kelly applies to per-leg Kelly). This provides context beyond the individual parameter definitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the detailed explanation of model families and response segments distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also mentions tradeable-edge knobs and the exclusion of Fed bets from ranking. However, it does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it reads from snapshots, explains decay computation, notes that gaps mean no scan, and limits history depth to 60-day TTL. No contradictions.

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

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

The description is well-structured: core purpose first, then detailed response format, then constraints and limitations. Every sentence adds value without filler. The length is appropriate for the complexity of the tool.

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

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

Given no output schema, the description comprehensively explains the response structure (tracked[], expired[], snapshot_dates[]) with details on each field (e.g., trend, decay_pp_per_day, lifespan_days). It covers edge cases like gaps and TTL, making the tool's behavior fully transparent.

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%, but the description adds meaning: it lists default values (14, 1wk) and clamping range (2-30 for days), and explains the 'window' parameter as 'snapshot family' with explicit options (24hr, 1wk, 1mo). This enhances understanding beyond the schema.

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

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

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

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

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

Provides clear context on when to use the tool, e.g., comparing a fresh wide edge to a 3-week-old wide edge, implying that it is for assessing edge age and decay. It does not explicitly state when not to use it or mention alternatives like 'polymarket_edges' for current snapshot, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds rich behavioral context: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and highlights forced directional risk and thin legs. 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 well-structured with sections for single-market, basket, and usage guidelines, and uses formatting like bold and caps for emphasis. While it is thorough, it could be slightly more concise; however, every sentence adds value given the tool's complexity.

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

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

Despite no output schema, the description thoroughly lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers edge cases and usage implications completely.

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 detailed descriptions for each parameter. The tool description adds further semantic meaning: explains the interaction between market and event parameters, default values, and how size_usd is interpreted differently in each mode (max spend vs target proceeds vs settlement notional).

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It uses specific verbs and resources, and differentiates from sibling tools like polymarket_arbitrage by positioning itself as a pre-trade risk check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (thin books, partial fills cause directional risk), providing clear context and exclusions for when to use.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds extensive detail: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases like non-equivalent bet shapes. No contradiction with annotations.

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

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

The description is front-loaded with core purpose and structured into clear sections. While slightly wordy with extensive detail, every sentence adds value and no information is redundant. Could be slightly more concise but overall efficient.

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

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

Given the complexity (3 parameters, no output schema), the description fully covers expected output (leg-by-leg prices, top_spreads_pp), safety fields, temporal alignment, skipped counters, and edge cases. It is complete and actionable for an agent.

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

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

Schema coverage is 100% and all parameters are documented in the schema. The description provides usage context (modes, examples) but does not add deeper semantic meaning beyond what the schema already offers. 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison, and explicitly describes two usage modes (topic shortcuts and explicit tickers).

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 explains when to use the tool: to compare prices across venues. It warns that pre-mapped topics often yield compatibility warnings and that real spreads are rarer than shortcuts suggest. It does not explicitly exclude other tools but provides sufficient context on interpretation.

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, destructiveHint=false, etc. Description adds that the tool returns attribute rows and geometry, which is behavioral info beyond annotations. No contradictions. Could have mentioned pagination or rate limits, but current disclosure is adequate.

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

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

Two concise sentences (40 words) front-loaded with purpose. Every sentence adds value: first states main action and parameters, second gives a typical usage pattern. No redundancy or fluff.

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

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

Given 6 parameters, no output schema, and standard GIS domain, the description is fairly complete. It explains query mechanics and sample usage. However, it could specify that geometry is returned in a standard format (e.g., GeoJSON), but this is minor. Overall, sufficient for an AI agent to use 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?

Input schema covers 100% of parameters. Description adds meaning by explaining SQL-like nature of 'where', comma-separated 'out_fields', and example use case. This helps an AI agent understand how to combine parameters effectively, exceeding schema alone.

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

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

Description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with SQL-like parameters. It distinguishes from sibling tools like search_datasets (which finds datasets) and layer_info (likely metadata) by focusing on data retrieval. Specific verb 'query' plus 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?

Description specifies the url comes from search_datasets, providing context for appropriate use. Gives example usage for sampling. However, does not explicitly state when not to use or mention alternative tools, but the guidance is clear enough for typical use.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds scoping to identifier, listing all keys when key omitted, and pairing with remember/forget. No contradiction.

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

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

Approximately 100 words, front-loaded with main purpose. Every sentence adds value. No redundancy.

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

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

For a simple one-parameter tool, description covers purpose, scope, usage context, and pairing with siblings. 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% so baseline 3. Description adds practical usage: examples and explanation of behavior when key is omitted (list all keys). Adds value beyond schema.

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

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

Description clearly states the tool retrieves saved values or lists keys, with explicit verb 'Retrieve' and resource 'value previously saved via remember'. Distinguishes from siblings by naming 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 clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairs with remember/forget for alternatives. Lacks explicit when-not-to-use but good enough.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds value by detailing the return fields (source, citation_uri, raw payload) and explaining the mark_read side effect, which updates the read state for subsequent calls.

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 (4 sentences) and front-loaded with the main purpose. Every sentence adds useful context without redundancy.

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

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

Despite no output schema, the description adequately covers what is returned (source, citation_uri, raw payload) and how parameters affect results. It also mentions polling and an alternative feed endpoint.

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 five parameters are described in the schema (100% coverage). The description enhances understanding by providing examples (e.g., type 'sec_8k', ISO timestamp for since) and explaining the behavior of mark_read.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. The verb 'Pull' and resource 'fired events' are specific, and the tool is distinct 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 mentions that polls work fine and provides an alternative endpoint for scripts/dashboards, giving context on when to use this tool. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses multi-source fan-out (SEC, GDELT, GNews, USPTO), fallback behavior (GDELT preferred, GNews on rate limit), soft-fail for USPTO sunset, and response format (structured changes grouped by source, total_changes, citation URIs). 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 fairly long but packed with essential information. It is front-loaded with query examples and prioritizes critical details. While it could be slightly shorter, every sentence contributes meaningful context, making it acceptable for the complexity.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats, no output schema), the description covers all necessary aspects: input parameter details, source behavior, fallback logic, response structure, and guidance on alternatives. It is self-contained and sufficient for correct invocation.

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

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

Schema coverage is 100%, and the description adds value: for 'since' it explicitly shows ISO date and relative shorthand examples, suggests '30d' for monitoring; for 'value' it clarifies ticker or CIK; for 'type' it notes only 'company' supported. This enriches parameter understanding.

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

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

The description clearly states the tool provides a change feed for a company within a time window, using examples like 'what's new with X' and explicitly distinguishes from 'entity_profile' for static data. The verb 'recent_changes' and resource 'company' are well-defined.

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

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

The description gives explicit guidance on when to use this tool vs alternatives: 'Use entity_profile instead when you want the static profile...'. It also recommends typical parameter values ('use '30d' or '1m' for typical monitoring'). This provides 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 already provide idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: authenticated vs anonymous persistence (24 hours for anonymous), and that data is scoped by identifier. No contradictions. However, it doesn't describe what happens on overwriting or any limits.

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

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

Three sentences, each earning its place. First sentence states purpose, second gives usage guidance, third provides technical details. No wasted words. Front-loaded with the core action.

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

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description is fully complete. It covers purpose, when to use, behavioral persistence, scoping, and pairing with siblings. No gaps remain.

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

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

Input schema coverage is 100%, with descriptions for key and value that are self-explanatory. The description adds context beyond schema by showing example key formats (e.g., 'subject_property') and emphasizing that value can be any text. This elevates 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's purpose: 'Save data the agent will need to reuse later'. It specifies the verb ('save') and resource ('data'), and distinguishes it from siblings by mentioning 'recall' and 'forget'. Examples like 'a resolved ticker, a target address' further clarify.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on scoping ('key-value pair scoped by your identifier') and persistence differences between authenticated and anonymous sessions. Pairs with recall and forget for retrieval and deletion, giving clear guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive; description adds valuable behavioral context: internal cascading through multiple endpoints, replacing 2-3 manual lookups, and detailed output structure (ticker, CIK, citation URI). 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?

Well-structured with front-loaded examples and logical flow. Slightly verbose but every sentence adds value (covers use cases, input, output, internal behavior). Could be slightly more concise but not wasteful.

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

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

Despite no output schema, description fully compensates by detailing return fields for each type (ticker, CIK, RxCUI, etc.), including citation URIs. Covers supported types, input formats, internal cascading, and replaces multiple lookups, providing complete context for an AI agent.

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

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

Schema coverage is 100% but descriptions are brief. The description enriches each parameter significantly: explains accepted formats for 'value' (ticker, CIK, name for company; brand/generic for drug) and what each type returns. Adds meaning beyond schema.

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

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

Description clearly states it resolves names to identifiers, with specific examples ('What's the ticker for…') and lists supported types. The verb 'resolve' and resource 'entity identifier' are explicit and distinct from sibling tools like 'entity_profile' or 'compare_entities'.

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

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

Explicit guidance to 'Use FIRST whenever you have a name but need an ID' provides clear context. It details supported types and input formats, but does not explicitly state when not to use or mention alternative sibling tools, missing full 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 non-destructive, idempotent, read-only, and open-world hints. The description adds the internal behavior of probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized—providing valuable context beyond annotations. 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 two dense sentences plus a quoted example, front-loading the primary action. Every sentence adds unique value without redundancy or filler.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also includes entity count constraints (2-8) from schema context. The description is fully sufficient for an agent to understand and invoke the tool.

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

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

Schema coverage is 100% with all parameters described. The description adds critical semantic nuance: first entity is the 'subject' for narrative, rest are competitors. It also clarifies model usage and API key conditions, going beyond schema definitions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verbs like 'compare,' 'probe,' and 'rank.' It distinguishes from sibling ai_visibility_check by emphasizing multi-entity comparison. The output format is explicitly mentioned.

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

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

The description gives context for use cases like 'competitive AI-marketing audits' and includes a concrete example question. While it doesn't list when-not-to-use or explicit alternatives, it implies usage by mentioning it probes each entity with ai_visibility_check, a sibling tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds critical context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and then expands with details. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall well-structured.

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

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

Despite no output schema, the description fully details the return structure: summary block fields, per-advisory detail, links, recent versions, and partial failure handling. This makes the behavior fully predictable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by mentioning scoped packages accepted and default behavior for version. This extra context boosts beyond baseline 3.

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

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

The description clearly states it's a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It identifies the resource (npm package) and action (scanning) with specificity. No sibling tool directly overlaps, so differentiation is inherent.

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: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me.' Also notes limitations (NPM only in v1) and alternatives for other ecosystems (deps.dev:version directly). Provides clear when-to-use and when-not.

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, so the safety profile is clear. The description adds context about the return structure and links to sibling tools, offering behavioral details 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 the action, no wasted words. Efficiently communicates purpose, return fields, and next steps.

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

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

Despite no output schema, the description lists all return fields (name, summary, record_count, owner/org, url), compensating fully. It also links to sibling tools, making the tool self-contained and easy to use.

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

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

Schema description coverage is 100% with each parameter documented. The description does not add new parameter semantics beyond the schema (e.g., it mentions 'by keyword' but the schema already provides examples). Baseline 3 applies.

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

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

The description clearly states the tool searches for open geospatial datasets by keyword, specifying the resource (datasets) and action (search). It lists the return fields, distinguishing it from sibling tools like query_layer and 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 explicitly tells what the tool returns (dataset metadata including a Feature Service url) and instructs to pass that url to query_layer or layer_info, providing clear usage guidance and context for when to use this tool versus 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?

Adds significant detail beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output includes offsets and scores. Complements annotations fully.

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 dense paragraph that front-loads purpose and then details technical specifics. No wasted words; 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?

Despite no output schema, the description explains return format (passages with offsets and scores) and embedding details. Covers truncation behavior and limits. 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%, but description adds extra context: explains the role of text (document to search), query (natural language examples), limit (max passages, default 5). Enhances schema understanding.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record', with specific use case for large records. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too big for the prompt, and suggests combining with ask_pipeworx_grounded. Provides clear context for when this tool is appropriate.

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

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

Annotations indicate write (readOnlyHint=false), idempotent (true), and non-destructive (false). The description adds rich behavioral context: requires OAuth, returns subscription id, explains delivery constraints (e.g., SMS 10/day cap, webhook auto-disable after 10 failures). No contradiction.

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

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

The description is front-loaded with the purpose and is structured with clear sections for types and delivery channels. It is somewhat verbose but every sentence adds value. Could be slightly more streamlined, but overall effective.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types, optional delivery), the description is comprehensive. It covers all types, delivery options, constraints (phone verification, rate limits), and return value (subscription id). No output schema, but return is explained.

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

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

Schema coverage is 100%. The description adds significant meaning beyond the schema: for each type, it provides examples and key details (e.g., sec_8k items, fred_series series_id). For nested objects like delivery, it explains webhook secret one-time return and HMAC verification. Enums are also elaborated.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (create/subscribe) and resource (subscription to alerts). It also distinguishes from sibling tools like list_subscriptions and unsubscribe by detailing subscription lifecycle.

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, including the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It also details supported types and delivery channels. While it doesn't explicitly state when not to use, the context is sufficiently clear.

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

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

Annotations already cover read-only, idempotent, open world, and non-destructive hints. The description adds valuable behavioral context by explaining the output structure (category-bucketed examples) and that it draws from a live catalog of tools, going 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 somewhat lengthy but every sentence serves a purpose. It is well-structured with examples and clear guidance, front-loading the primary use case. Minor improvement could be tightening wording slightly, but overall efficient.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It covers what the tool returns, when to use it, the parameter options, and behavioral traits. No gaps remain.

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 description. The description adds meaning by listing the possible topic values (finance, pharma, etc.) and explaining the behavior when omitted (cross-category spread), which is more helpful than the schema alone.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with tool+argument shape. It effectively distinguishes from sibling tools by positioning itself as the first tool to use when the agent doesn't know Pipeworx's capabilities.

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

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

The description explicitly says to use this tool FIRST when unaware of Pipeworx's capabilities or to learn how to call meta-tools. It also explains the two calling modes (no arguments for full spread, topic argument to focus). While it doesn't explicitly state when NOT to use, the context makes it clear.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds significant behavioral context: ownership enforcement (beyond idempotency), soft deactivation rather than deletion, and that historical events remain available. No contradictions.

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

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

Two sentences, both front-loaded with critical information. No filler or redundancy.

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

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

Given a single required parameter, no output schema, and a simple mutation operation, the description fully covers the tool's behavior, including ownership and deactivation semantics. 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 a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description does not add extra semantic meaning beyond what the schema already provides, 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 'Cancel a subscription by id', specifying the verb 'cancel' and the resource 'subscription by id'. It naturally 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 explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding usage. It also explains that the row is deactivated (not deleted), but doesn't explicitly state when not to use this tool or name alternatives for full deletion.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses the data source (SEC EDGAR + XBRL), the return structure (verdict, structured form, actual value, citation, delta), and the scope (company-financial claims). No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured: examples first, then usage guidance, then returns. Every sentence adds value, though could be slightly more concise without losing information.

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

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

Given the tool's single parameter, lack of output schema, and rich annotations, the description covers purpose, usage, returns, and constraints adequately. It could mention limitations (e.g., only public US companies) but is otherwise complete.

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

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

Schema coverage is 100% and the schema already describes the 'claim' parameter with examples. The description repeats similar examples but doesn't add substantive new 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 that the tool validates natural-language claims against authoritative sources for company-financial data, with specific examples. It distinguishes from siblings by noting it replaces 4-6 sequential calls.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial). Does not explicitly mention when not to use or alternatives, but context with siblings makes it clear.

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