Arcgis Lacounty

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value beyond these by explaining cost implications (free default model, BYO key for Anthropic) and return structure (per-model and combined view). 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 a single paragraph with clear front-loading of purpose, followed by specifics on models and cost, then return structure, then use cases. Every sentence adds value with no fluff.

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

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

Despite lacking an output schema, the description fully explains the return format (per-model {score, confidence, signals, raw_response} + combined view). All 4 parameters are adequately documented via schema and description. Use cases are given, making it complete for decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: explains when _apiKey is needed, defaults for models, the role of context for disambiguation, and how parameters interact (e.g., models list and _apiKey). This goes well beyond the schema descriptions.

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

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

The description uses a specific verb ('probe') and resource ('LLMs') and clearly states the output (visibility score 0-100). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on scoring LLM awareness rather than general scanning.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not contrast with sibling tools or state when not to use. While clear, it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details: routes to specific tools, returns structured answers with pipeworx:// citation URIs, works on every tier. No contradictions.

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

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

Description is thorough but front-loaded with the key recommendation. Each sentence serves a purpose, though it is somewhat long. Could be slightly more concise.

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

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

Given the tool's complexity (routing to many sources) and full schema coverage, the description provides sufficient context. No output schema exists, but the description states it returns 'structured answer with stable pipeworx:// citation URIs', which is adequate.

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

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

Schema coverage is 100% with each alias described. The description does not add additional meaning beyond the schema; examples are given but no new semantic constraints or formats.

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

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

The description specifies a clear verb ('routes questions') and resource ('4,396 tools across 1102 verified sources'), distinguishing it from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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 prefer this tool over web search, when to use alternatives (e.g., ask_pipeworx_grounded, deep_research), and provides concrete examples. 'START HERE' and 'Step up only when needed' offer 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 mark this as readOnlyHint, idempotentHint, etc. The description adds context: extra cost, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and that it uses only tool result content. 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 dense and front-loaded with purpose. Though long, every sentence adds value. Minor redundancy might be trimmed but overall efficient for a complex tool.

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

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

Despite no output schema, the description fully documents return structures for success and failure, including fields like answer, evidence, confidence, source, fetched_at, and refusal reasons. It covers behavior, use cases, and cost, making the tool self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter semantics beyond documenting aliases for 'question'. The schema already fully describes parameters.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from sibling 'ask_pipeworx' by emphasizing that it extracts answers only from tool results and refuses if data doesn't directly answer.

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: 'high-stakes reads', 'whenever an answer will be quoted, cited, or acted on'. Provides clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of an extra LLM call.

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 discloses behavior beyond annotations: low-confidence resolutions short-circuit with status, closed markets return status, wide-spread markets carry tradeability, resolution-rule risk is explained, and news fields include fallback handling. These details add significant transparency about edge cases and safety measures, going well beyond the readOnlyHint and idempotentHint 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 verbose with multiple paragraphs and detailed examples. While it is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), it could be more concise. The front-loading of the main purpose is good, but some redundancy exists (e.g., repeating caveats). Given the complexity, the length is somewhat justified, but a 3 is appropriate.

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

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

Given the tool has 3 parameters and no output schema, the description is remarkably thorough. It covers input formats, classifiers with examples, fan-out logic for various categories, response shapes with field details, resolver contract, parent_event extraction, news field metadata, safety mechanisms, and resolution-rule risk. It leaves no obvious gaps for an agent to misinterpret.

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

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

Schema coverage is 100%, so baseline is 3. The description mostly repeats parameter descriptions from the schema (e.g., market input formats, depth options). It does not add new meaning beyond what the schema already provides, but it is consistent and sufficient.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and explains the process (resolves market, classifies, fans out, returns evidence packet). This specificity differentiates it from sibling tools like ask_pipeworx or deep_research, which are more generic.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of fan-out for different bet types. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling context implies it is specifically for Polymarket bets.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA, clinical trials), handling of off-calendar fiscal years, result sorting by primary metric, and inclusion of citation URIs. It also states that it replaces 8-15 sequential lookups, providing efficiency insight. No contradictions with annotations.

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

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

The description is a single paragraph that packs essential information efficiently. It front-loads example queries, then covers usage preference, per-type details, and result features. While dense, it is well-structured and every sentence adds value. A slightly more compact handling might be possible, but it remains clear.

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

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

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description provides comprehensive context. It covers what data is returned for each type, how results are sorted, and the presence of citation URIs. It also explains the entity count range. This fully equips an agent to understand the tool's functionality without needing additional documentation.

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 significantly enriches parameter meaning. For 'type', it explains what each enum value retrieves (e.g., revenue, net income for companies; adverse events, approvals for drugs). For 'values', it clarifies the required format (tickers/CIKs for company, names for drug) and the size constraints (2–5). This goes beyond the basic schema descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 entities (companies or drugs) in one call. It uses specific verbs like 'compare' and provides example queries, making the purpose unambiguous. It also distinguishes itself from sibling tools like entity_profile by emphasizing parallel vs. single-entity lookup.

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

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

The description explicitly advises preferring this tool over sequential single-entity lookups when comparing entities. It defines when to use 'company' vs. 'drug' and details the data returned. However, it omits explicit guidance on when not to use it (e.g., for a single entity), though it's implied by the '2–5' requirement. A minor gap prevents a perfect score.

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

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

Annotations already indicate safe, idempotent read behavior. The description adds crucial context: not open-web search, returns findings with verbatim evidence and gaps, never invents, includes time expectation (15-60s), and account tier restrictions. 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 long but front-loaded with critical info (account requirement, alternative tool). Bold text highlights key points. Some redundancy exists (e.g., 'not open-web search' repeated), but overall each sentence adds value. Slightly verbose, but justified by tool 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 explains the return format: findings packet with evidence, confidence, source, fetched_at, citations, and gaps. It also sets time expectations and covers when results may be empty. For a complex tool with 2 parameters and no output schema, this is exceptionally complete.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8) and notes that 'thorough' requires a paid plan. It also reinforces that the question should be in natural language and broad/multi-part is acceptable.

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 'Grounded multi-source research across Pipeworx's 1102 STRUCTURED data sources' and decomposes questions into facets. It distinguishes from siblings like ask_pipeworx by specifying it's not open-web search and best for broad/multi-part questions.

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: 'Best for broad/multi-part questions over structured data' and when to avoid: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also provides account requirement and alternative for non-signed-in users.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it returns top-N relevant tools with full schemas ready to call, which is useful beyond annotation hints.

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

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

Description is front-loaded with purpose and domains, but could be slightly shorter. Still well-structured with clear sentences.

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

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

Given no output schema and full parameter coverage, description adequately explains returned content (names, descriptions, schemas) and use case. Lacks output format details but acceptable for discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds explanation of query parameter purpose but largely mirrors schema aliases and descriptions.

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

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

The description explicitly states the tool finds tools by describing data or task, listing many domains. It clearly distinguishes from sibling tools that perform specific tasks rather than discovery.

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 advises when to use (browse, search, discover) and to call first when many tools are available. It lacks explicit exclusion criteria but provides clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, patent soft-fails after May 2025, and fallback mechanisms. It could mention rate limits or latency but overall good.

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

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

The description is lengthy but well-structured and information-dense. It front-loads with examples and core purpose. Every sentence adds value, though it could be trimmed slightly without loss. Still highly effective for an 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?

Despite having no output schema, the description thoroughly explains the return values: CIK, company_name, recent_filings with URIs, fundamentals (specific fields), patents with caveat, news fallback, LEI. It also covers parameter constraints and required inputs.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value beyond the schema by explaining that names are not supported, how to use resolve_entity as alternative, providing examples (zero-padded CIK), and noting that person/place types are coming soon.

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: full cross-source profile of a US public company in one parallel call. It provides multiple example queries and lists the data sources and returned fields. It distinguishes from sibling tools like resolve_entity (needed for names) and explicitly says to prefer this over chaining single-source lookups.

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

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

The description gives explicit guidance on when to use (holistic view) and when not (names not supported, requires ticker or CIK). It mentions alternatives (single-pack SEC/XBRL/news lookups) and prerequisites (use resolve_entity first if only have name). Also includes limitations like patent soft-fail.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and pairing, which enriches understanding 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?

Three compact sentences: first defines action, second provides usage scenarios, third suggests related tools. No waste, information is front-loaded.

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

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

Given low complexity (1 param, no output schema), the description fully covers purpose, usage scenarios, and tool relationships. It is sufficient for an agent to correctly select 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% (key parameter fully documented). Description merely says 'by key', adding no extra meaning beyond the schema's description 'Memory key to delete'. 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 verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes from siblings 'remember' (store) and 'recall' (retrieve) by specifying deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with 'remember and recall', but does not explicitly state when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral details: fetches page, extracts title/description/key links, and outputs standard markdown format. 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 cover purpose and process, followed by a list of use cases. Every sentence adds value; no waste. Front-loaded with main action.

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

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

Despite lacking an output schema, description explains output format and purpose. Two parameters are fully documented in schema. Complexity is low, and description covers all necessary context.

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

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

Schema coverage is 100% with clear descriptions for both parameters. Description does not add new meaning beyond the schema, so baseline score of 3 applies.

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

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

Description clearly states verb 'Generate' and resource 'llms.txt file'. Specifies target URL and distinguishes from siblings by focusing on llms.txt generation, which is unique among listed sibling tools.

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

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

Provides three concrete use cases (client indexing, own project, competitor audit) but does not explicitly state when to avoid using it or mention alternative tools for similar tasks.

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

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

Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds behavioral transparency by specifying what the tool returns (fields, geometry type, record count, capabilities), which goes beyond the annotations. No contradictions.

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

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

The description is a single concise sentence that is front-loaded with the key action and resource. It efficiently lists the returned components without unnecessary words or fluff. Every word serves a purpose.

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

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

Given the simple one-parameter input, full schema coverage, and annotations covering safety, the description is complete. It specifies the input format and the full set of outputs. No additional context is needed for correct usage.

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

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

The input schema has 100% description coverage with a clear description and example for the 'url' parameter. The tool description simply says 'by url', reiterating the schema. Since schema coverage is high, the description adds minimal additional semantics, earning a baseline score 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 action (Get), the resource (an ArcGIS Feature/Map Service layer's schema), and specifies the components returned: fields with name and type, geometry type, total record count, and capabilities. This distinguishes it from sibling tools like query_layer, which likely retrieves actual data rather than schema.

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

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

The description explains how to use the tool (by providing a url) but does not provide explicit guidance on when to use this tool versus alternatives. For example, it could mention using this to discover schema before querying with query_layer. The lack of usage context or when-not-to-use instructions reduces the score.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return fields and default active-only behavior, providing useful context beyond annotations.

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

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

Two sentences, no redundancy, front-loaded with verb-object. 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?

Simple tool, one parameter, no output schema. Description covers purpose, usage, and return fields completely. No gaps given the complexity.

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

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

One parameter with 100% schema description coverage. Description does not add 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?

Clear verb 'list' and resource 'subscriptions'; specifies returned fields; distinguishes from siblings (subscribe/unsubscribe).

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.'

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

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

The description discloses rate limits ('Rate-limited to 5 per identifier per day') and quota impact ('Free; doesn't count against your tool-call quota'). Annotations are not contradicted (readOnlyHint=false, destructiveHint=false), and the description adds context beyond annotations.

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

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

The description is concise (around 100 words) and front-loaded with the main purpose. It is well-structured with clear sentences, though it could be slightly more compact.

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 feedback tool with no output schema, the description fully covers usage, rate limits, what to include, and expected impact. It provides all necessary context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context for the 'type' enum (e.g., associating each enum value with a scenario) but does not significantly expand on parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise), making it highly specific and distinct from sibling tools.

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

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

The description explicitly tells when to use the tool for each feedback type and provides guidance on what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It also notes the team reads digests daily and directly affects roadmap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, caching duration (5min-1h), and aggregate-only nature. This goes 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 (5 sentences) with front-loaded purpose, structured use cases, and efficient additional details. 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 low complexity (1 optional param, no output schema), the description is nearly complete. It explains return contents, use cases, caching, and data origin. Could optionally mention explicit return format, but not necessary.

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

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

Schema coverage is 100% with parameter description included. The description adds minor context about window semantics (hot vs steady-state), but essentially the schema already conveys the point. Baseline 3 is appropriate.

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

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

The description clearly states it returns trending data (top tools, packs, call volume) over time windows, distinguishing it from sibling tools like ask_pipeworx or discover_tools. The verb 'returns' and specific resources make the purpose unambiguous.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and alignment checking. This guides the agent on when to use the tool, though no explicit when-not or alternative tools are mentioned.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds detailed behavior: walks child markets, checks monotonicity, computes partition check, performs fill check against live CLOB depth. 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?

Front-loaded with requirement and mode distinction. All sentences are informative, but the description is lengthy (several paragraphs) and could be trimmed slightly without losing essential details.

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 explains response structure (opportunities[] with fields) and fill check details. Covers semantic anchor, partition filter, and sibling tool reference. Complete enough for effective 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 coverage is 100%, but description adds example slugs, explains modes, and consequences of each parameter. Significantly enhances meaning beyond schema descriptions.

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

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

Specific verb 'Find' and resource 'arbitrage opportunities on Polymarket' with clear distinction between event and topic modes. Differentiates from sibling tools like polymarket_fill_risk by explicitly directing users there for custom sizing.

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

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

Explicitly states when to use each mode, warns that calling with no args fails, and provides criteria for not trading (realizable_edge_pp ≤ 0). Mentions alternative polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds substantial behavioral context: caching (1h at KV level), internal diagnostics, edge calculation details (e.g., slippage, Kelly caps), and the '24h-move warning'. 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 front-loads the purpose and is well-structured with sections (segments, knobs, response). However, it is verbose with deep model-family explanations, which could be condensed without loss of clarity 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 the tool's complexity (9 parameters, no output schema), the description provides exhaustive detail on response structure (by_segment, fed_candidates, diagnostics), caching behavior, and edge calculation. It equips the agent to understand output and filter opportunities 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% with detailed parameter descriptions. The description adds broader context for some parameters (e.g., min_partition_leg_kelly explains why min_kelly doesn't apply), but this is incremental. The schema already does the heavy lifting, so baseline 3 is appropriate.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model- and structure-driven edges.

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

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

The description explicitly frames the use case as 'what should I bet on today' and explains why paging is unnecessary. It details tradeable-edge knobs for filtering. However, it does not directly contrast with siblings or state when not to use this tool.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds significant behavioral detail: it explains that snapshots are written on cache-miss (so gaps mean no scan), that decay numbers come from daily closes (not intraday), and provides a detailed response structure (tracked[], expired[], snapshot_dates[]). 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 dense but well-structured, with clear sections (RESPONSE, LIMITS) and front-loaded purpose. Every sentence adds value, though it could be slightly more concise. The format aids readability 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 details the response structure (tracked[], expired[], snapshot_dates[]) and their contents. It also covers parameter defaults, constraints, and data source limitations. The description 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 description coverage is 100%, so baseline is 3. The description adds value by specifying defaults (days default 14, window default '1wk'), clamps (days max 30, though schema says clamp 2-30), and interpreting 'window' as 'snapshot family'. This extra context improves parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It addresses a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking 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?

The description provides context on when to use the tool, explaining that a fresh wide edge and a 3-week-old wide edge are different trades. It implies usage for assessing edge persistence without explicitly stating when not to use. The LIMITS section adds constraints (history depth, data source), which helps guide appropriate 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 read-only, non-destructive, idempotent. The description adds rich behavioral context: it is a risk check, does not execute trades, explains outcomes like 'clean|degraded|cannot_fill', and warns about stranded positions. 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 lengthy but well-structured with clear sections: overall, single-market, basket, usage warnings. It is front-loaded with the core purpose. Every sentence adds value given the complexity, though could be slightly more concise.

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

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

Given the complexity (two modes, no output schema), the description covers input, behavior, output fields, risks, and real-world guidance. It details return fields for both modes, explains edge cases like thin legs and directional risk, and provides a threshold for usage.

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

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

Schema covers all 4 parameters with descriptions. The description adds significant meaning: clarifies the two modes (market vs event), explains defaults, basket interpretation of size_usd, and side auto-detection logic. This goes well 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists return fields. It explicitly differentiates from siblings by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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

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

The description provides explicit when-to-use guidance: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the rationale (thin books, partial fills). It does not explicitly state when not to use, but the threshold and context imply for smaller trades it may be optional.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses key behavioral traits: the existence of two modes, the meaning of compatibility_warning in two distinct scenarios, temporal alignment checks, and counters for skipped comparisons. This adds significant context.

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

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

The description is thorough but well-structured with clear sections (modes, response, safety fields). While it is somewhat long, every sentence contributes information, and the key points are front-loaded.

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

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

Given the absence of an output schema, the description fully explains the response structure, including compatibility_warning conditions, temporal alignment, and skipped comparison counters. It covers all necessary aspects for an agent to interpret results correctly.

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

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

The input schema already provides 100% coverage with descriptions for each parameter. The description adds value by explaining the interplay between topic and explicit overrides, and by enumerating the allowed topic values in context. This goes beyond 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 function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs and resources, and is distinct from sibling tools like polymarket_arbitrage which operate within a single venue.

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 details two modes of use (topic shortcuts and explicit pairings) and provides warnings about compatibility and the rarity of tradeable spreads. However, it does not compare directly with alternative tools or explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns both attribute rows and geometry, and gives sample SQL syntax. This extra behavioral context 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 two tight sentences plus a usage tip. It is front-loaded with the core purpose, and every sentence adds essential information 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?

For a tool with 6 parameters, 100% schema coverage, and rich annotations, the description covers the key aspects: input source, SQL-like parameters, and return type (attributes + geometry). It lacks explicit detail on pagination or output structure but remains sufficient for selection.

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 value by explaining that `where` is SQL-like, `out_fields` is comma-separated, and provides example values (e.g., 'POP DESC' for order_by). It also clarifies defaults implicitly through the sample usage.

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

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

The description clearly states the verb 'Query' and the resource 'ArcGIS Feature Service / Map Service layer'. It distinguishes from sibling tools like 'search_datasets' (which finds datasets) and 'layer_info' (metadata) by specifying the action and input source.

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

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

The description implies the URL should come from 'search_datasets', providing context. It also gives a sample usage pattern ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly exclude when not to use or name alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so description's mention of retrieval is redundant but adds scoping detail ('scoped to your identifier') and listing behavior. No contradictions. 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?

Three sentences, front-loaded with primary function. Slightly verbose with examples but well-organized. Every sentence contributes 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?

No output schema exists, so description should clarify return format. It says 'value' or 'list all saved keys' but doesn't specify data types or structure. Examples hint at flexibility, but lacks precise format. Adequate but not comprehensive.

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

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

Schema coverage is 100%, and the description reinforces the schema's explanation of omitting key to list all keys. No additional meaning beyond the schema's property description. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves a value by key or lists all keys, using specific verbs 'Retrieve' and 'list'. It distinguishes from sibling tools 'remember' and 'forget' by explicitly mentioning them and their actions (save, delete).

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

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

Provides explicit when-to-use context: 'to look up context the agent stored earlier' with concrete examples (ticker, address, notes). Implicitly advises against re-deriving information. Explicitly describes pairing with 'remember' and 'forget', covering when to use alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds that mark_read:true flags events as read, altering state for future calls. It also notes polling behavior and the return format (source, citation_uri, raw payload). No contradictions with annotations.

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

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

The description is a single paragraph of 4 sentences, front-loading the main purpose and then providing specific details. 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?

Despite no output schema, the description explains what the return includes (source, citation_uri, raw payload) and the effect of mark_read on subsequent calls. The 5 optional parameters are well-documented via both schema and description, making the tool's usage fully understandable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'type' filters by subscription type, 'since' is an ISO timestamp, 'mark_read' flags returned events read in the same call, and 'unread_only' returns only unread events. This surpasses the schema descriptions.

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

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

The description explicitly states it 'pulls fired events from your subscription feed' and returns specific fields (source, citation_uri, raw payload). It also highlights filtering by type and since, clearly distinguishing it from sibling tools like '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 provides clear context: 'polls work fine' and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). It explains the mark_read flag's effect on subsequent calls. However, it does not explicitly state when not to use the tool or list alternatives beyond the API endpoint.

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

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

The description discloses rich behavioral details beyond annotations: it fans out to multiple sources (SEC, GDELT, USPTO), explains fallback behavior (GDELT→GNews when rate-limited or 5xx), mentions soft-fail for patents (PatentsView API sunset), and describes the return structure (changes[] grouped by source, total_changes count, citation URIs). This matches annotations (readOnlyHint, idempotentHint) without contradiction.

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

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

The description is well-structured, starting with example queries to set context, then explaining the fan-out mechanics and return format. Every sentence adds value. However, it is slightly verbose; it could be tightened without losing clarity, which prevents a top score.

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

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

Given the tool's complexity (multi-source, fallbacks, no output schema), the description covers most aspects: source fan-out, fallback logic, return structure, and parameter details. It does not detail error handling or rate limits beyond the GDELT→GNews fallback, but overall it is 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 description coverage is 100%, but the description adds substantial value: it explains 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), clarifies 'type' only supports 'company', and specifies 'value' can be ticker or zero-padded CIK. This adds meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose with concrete example queries ('What's new with X', 'latest on Y'), specifies it fetches changes from SEC EDGAR, GDELT/GNews, and USPTO, and explicitly distinguishes itself from sibling tool 'entity_profile' by contrasting use cases ('Use entity_profile instead when you want the static profile').

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

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

The description provides explicit usage guidance: it includes example queries for when to use the tool, specifies the 'since' parameter with both ISO and relative shorthand options, and directly tells when to use the alternative tool ('entity_profile') instead. This gives clear when-to-use and when-not-to-use context.

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

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

The annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds context about scoping by identifier, persistence for authenticated vs anonymous users (24 hours), which goes beyond annotations. No contradictions.

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

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

The description is four sentences, each providing essential information: purpose, usage, storage details, and pairing with siblings. No unnecessary words.

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

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

Given the low complexity (2 params, no output schema), the description fully covers purpose, when to use, behavioral traits, and parameter context, leaving no gaps.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds naming examples (e.g., 'subject_property') and context (findings, addresses, preferences), which adds semantic value beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, specifying the resource as a key-value pair. It distinguishes from siblings like recall and forget, and uses specific verbs like 'save' and 'store'.

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

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

The description provides explicit when-to-use guidance: when discovering something worth carrying forward (e.g., ticker, address, preference). It also mentions pairing with recall and forget, which are siblings, but does not explicitly state when not to use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context by mentioning internal cascading lookup endpoints and auto-disambiguation, which goes beyond what annotations provide. 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 and front-loaded with purpose and usage guidance. It includes examples and detailed type-specific information. While somewhat long, each sentence adds value, and it avoids unnecessary 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 simplicity (2 parameters, no output schema) and strong annotations, the description is very complete. It explains return values per type, including citation URIs, and covers disambiguation behavior. 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?

With 100% schema coverage, baseline is 3. The description adds meaning by specifying acceptable input formats for each type (e.g., ticker, CIK, name for company; brand or generic for drug) and describing return fields per type, which enriches the 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 resolves names to canonical identifiers and provides example queries. It distinguishes itself from siblings by emphasizing 'use FIRST whenever you have a name but need an ID', though it doesn't explicitly compare with sibling tools like compare_entities or entity_profile.

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

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

The description explicitly says when to use the tool ('use FIRST whenever you have a name but need an ID') and outlines supported entity types with input examples. It does not explicitly state when not to use, but the guidance is clear 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 declare safe read-only behavior. Description adds value by explaining the composite process (probes each entity, ranks), output format (ranked list with score, confidence, signal density), and that the first entity is treated as subject. No contradictions.

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

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

Description is concise (4-5 sentences) and front-loaded with primary purpose. Every sentence adds information without redundancy. Efficient use of space.

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 explains tool's behavior, output format, and use case. Given complexity (composite tool, 4 params), it provides sufficient detail for correct agent 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 covers all parameters with descriptions (100% coverage). Description adds context: treating first entity as 'subject' for narrative, and context parameter disambiguates common names. This 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 the tool's purpose: compare AI visibility across multiple entities side-by-side, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

Description provides a concrete use case: competitive AI-marketing audits, with an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or alternatives to exclude.

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 behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed list appears on timeout. This complements the readOnlyHint and idempotentHint 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 detailed but well-structured: purpose first, then usage, return data, constraints, and failure behavior. Every sentence is informative, though slightly long. 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, the description comprehensively explains return fields (summary block, per-advisory, links, alternatives) and covers ecosystem limitations and graceful degradation. No significant 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 description adds minimal new meaning. It clarifies that package accepts scoped names and version defaults to latest published, but these are already implied by schema descriptions. No additional semantics beyond the schema.

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

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

The description clearly states it's a composite check for 'should I add this npm package to my project', explicitly naming sources (deps.dev, bundlephobia) and data returned. It is distinct among sibling tools, which are unrelated to package scanning.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes limitation 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear when and 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, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds behavioral context about output contents but doesn't disclose potential limitations like pagination, rate limits, or response size. It does not contradict annotations.

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

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

Two sentences: first states action and scope, second states return fields and next steps. No wasted words, front-loaded with verb and resource. Ideal structure for an 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?

Despite no output schema, the description lists all returned fields (name, summary, record_count, owner/org, url) and explains the expected follow-up (pass url to query_layer/layer_info). This is complete for a search tool that delegates detailed queries to sibling tools.

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 three parameters have descriptions in the input schema (100% coverage), so baseline is 3. The tool description mentions 'by keyword' which aligns with the query parameter, but doesn't add new semantic detail beyond the schema. No enums or nested objects, so no missed opportunities.

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 'Search Los Angeles County GIS open geospatial datasets' with specific examples (parcels, parks, etc.). It precisely defines the verb (Search) and the resource (GIS datasets), and distinguishes from sibling tools like query_layer and layer_info by noting that the output url is to be passed to those tools.

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

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

The description explicitly tells the agent to pass the returned url to query_layer or layer_info, linking to sibling tools. It provides keyword examples. However, it does not explicitly state when not to use this tool or compare it directly with alternatives beyond the mention of downstream tools.

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

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

Annotations already indicate safe read-only behavior. The description adds valuable internal details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output format (passages with offsets and scores). 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?

Two sentences convey purpose, usage, technical details, and pairing. No fluff. Front-loaded with purpose. Efficient and clear.

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

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

For a 3-param tool with no output schema, the description covers purpose, usage scenario, internal mechanism, output details, and pairing with a sibling. Fully sufficient for correct agent 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% with descriptions. The description adds context for the query parameter with concrete examples and explains the text parameter's max length and truncation behavior, enriching 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 'Semantic search INSIDE a fetched record' and uses specific verbs and resources. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and implying its use case is for searching within a large text, making the purpose unambiguous.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit. It also pairs with a sibling. However, it does not explicitly mention when not to use it or alternative tools for general search, but the context is clear enough.

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

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

Annotations provide base behavior (non-readonly, idempotent, etc.), but description adds significant context: account requirement, subscription type details, delivery channel constraints (email/SMS caps, webhook auto-disable after 10 failures). 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?

Front-loaded with purpose and key constraints. While comprehensive, some details (e.g., webhook HMAC description) are slightly verbose but still valuable. Could be trimmed marginally without losing content, 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?

Given no output schema, description mentions return value (subscription id) but doesn't detail full response structure. For a tool with 3 params and nested objects, it covers creation, types, and delivery well, but idempotent behavior (whether duplicate creations return same ID) is not clarified. Minor gap in completeness.

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

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

Despite 100% schema coverage, description adds extensive meaning beyond property definitions: provides real-world examples for each type's params, clarifies required fields (e.g., sponsor or condition for clinical_trial), and explains delivery sub-parameters (SMS must match verified phone, webhook HMAC signing). Adds high value.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' and explicitly mentions return value (subscription id). Distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides detailed when-to-use guidance including required account type (Pipeworx OAuth), supported subscription types with examples, and delivery channel options with constraints (e.g., SMS 10/day cap, webhook signing). Implicitly tells when not to use (if not needing persistent subscriptions).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it draws from a live catalog and returns specific categorized questions. No contradictions; it provides useful behavioral context beyond annotations without adding unnecessary detail.

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

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

The description is somewhat verbose but front-loaded with common queries and well-structured with lists. Every sentence contributes value; minor conciseness loss due to redundancy like listing examples inline.

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

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

The tool has one optional parameter and no output schema. The description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument shapes), filling the gap left by missing output schema. No missing context for effective 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 coverage is 100% with a single optional 'topic' parameter described. The description adds meaning by listing possible focus areas and explaining how to use the parameter to narrow results, exceeding what schema alone provides.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns categorized example questions, using verbs like 'returns category-bucketed example questions' and distinctively positions itself as the first tool to use when unfamiliar with Pipeworx, differentiating it from siblings.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains when to omit or pass a topic argument, providing clear context for 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?

Discloses that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. Annotations already indicate non-destructive and non-readOnly, so description adds useful nuance.

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, no fluff. Front-loaded with 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?

Simple 1-param tool; description covers purpose, ownership, effect, and ties to recent_alerts. No gaps for typical use.

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

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

Schema covers 100% of parameters with a clear description for 'id'. Description adds that the id comes from subscribe, but this is implicit. 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 'Cancel a subscription by id', specifying the action and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), implying that the tool should only be used for your own subscriptions. No explicit when-not, but clear context.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it returns a verdict with structured form, actual value with citation, and percent delta. Also notes it's v1 and only supports US company-financial claims. 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?

Fairly concise despite length; front-loaded with example phrases. Every sentence adds value, though could be slightly more streamlined 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 one required parameter, no output schema, and annotations present, the description fully covers purpose, usage, domain limitations, and return structure. Complete for an AI agent to use correctly.

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

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

Only one parameter 'claim' with schema description. Description adds domain context (company-financial), examples, and return format, going beyond the schema. Schema coverage is 100%, baseline 3, but description adds value.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific examples and domain (company-financial claims). It distinguishes from siblings by noting it replaces multiple 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 when to use: 'whenever the agent needs to check whether something a user said is factually correct.' Provides trigger phrases. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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