Arcgis Lincolncountync

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

Annotations already declare readOnlyHint true, idempotentHint true, etc. Description adds beyond annotations: default model, optional Anthropic probe with cost, return structure (per-model fields + combined view), and that it probes multiple LLMs. 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 front-loaded with purpose. Every sentence adds value (purpose, defaults, return format, use cases). No wasted words.

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

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

Given no output schema, description adequately explains return format (per-model and combined view). Covers cost, default model, optional probing, and use cases. Annotations provide safety profile. Complete for a probing tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by noting default model, that '_apiKey' is passed directly to Anthropic, and that 'context' helps disambiguate. This enriches understanding 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?

Description uses specific verb 'probe' and resource 'LLMs for knowledge about an entity' with a clear scoring output. It distinguishes from siblings like 'ask_pipeworx' (question-answering) and 'deep_research' (broader research) by focusing on AI visibility scoring.

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

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

Explicitly states use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Implies when not to use (e.g., not for direct Q&A), though no explicit alternative is named. Cost implication (free vs. BYO key) provides 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 description adds significant behavioral context beyond the annotations: it reveals internal routing across 4,552 tools and 1,160 sources, mentions that it fills arguments automatically, and highlights the return of structured answers with stable citation URIs. These details are not covered by the annotations (readOnlyHint, openWorldHint, idempotentHint) and thus provide valuable transparency.

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

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

The description is relatively long but well-structured: it opens with a strong directive, lists use cases, explains internal workings, provides examples, and closes with guidance on alternatives. Every sentence adds value, though some redundancy exists (e.g., multiple lists of question types). It is appropriately sized for a complex tool and is front-loaded with the most important advice.

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 broad scope (factual questions across many domains), the description is remarkably complete. It covers the types of questions it handles, the internal mechanism, the output format (citations), the relationship to sibling tools, and triggers for when to use alternatives. No output schema exists, but the description adequately explains what the tool returns.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides (e.g., accepting natural language). While the description includes examples and broader usage context, it does not enrich the semantic understanding of individual parameters beyond the schema's existing 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: to answer factual questions using authoritative structured data, and explicitly distinguishes it from siblings like ask_pipeworx_grounded and deep_research. It uses a strong opening directive ('PREFER OVER WEB SEARCH') and lists specific use cases (SEC filings, FDA drug data, etc.), making the purpose unmistakable.

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

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

The description provides explicit guidance on when to use this tool, including trigger phrases ('what is', 'look up', 'find'), and when not to use it (for hallucination-resistant answers or broad multi-part questions). It names alternatives (ask_pipeworx_grounded, deep_research) and explains the upgrade path, fulfilling the criteria for explicit when/when-not/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?

Discloses extra LLM call cost, return structure with fields like evidence, confidence, refusal_reason, and specifics of failure modes. Adds significant behavioral detail beyond annotations which already indicate safety.

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 relatively long but well-structured: overall purpose first, then detailed process, then usage guidance. Each sentence contributes, 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 tool's complexity (single parameter, no output schema), the description thoroughly covers return format, failure reasons, and use cases, making it fully informative.

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

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

Schema has 100% coverage with 6 aliases for the same parameter. Description mentions natural language and aliases but adds no new semantic meaning beyond 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?

Clearly states it's a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling tool ask_pipeworx for casual lookups. Mentions specific verb and resource.

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 when answers will be quoted, cited, or acted on, and to avoid invention of facts. Also tells to prefer ask_pipeworx for casual lookups, providing clear when-not guidance.

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

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

The description is richly detailed, covering resolution, classification, fan-out, response shapes, resolver contract, parent event extraction, news fallback, safety, spread warnings, and resolution-rule risk. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and well-supplemented.

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

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

The description is long (over 600 words) but well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Given the tool's complexity, the length is justified, but some repetition could be trimmed.

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

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

Given the tool's complexity (multiple classifiers, response shapes, safety mechanisms) and having no output schema, the description is exceptionally complete, covering all edge cases and providing detailed behavioral 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%. The description adds meaning beyond schema: explains market accepts slug, URL, or question text; depth options and defaults; include_raw default and effect. Parameter descriptions are comprehensive and helpful.

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

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

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 types (slug, URL, question text) and output (evidence packet + market-vs-model comparison), distinguishing it from siblings like polymarket_arbitrage.

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

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

Explicit usage examples are given: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' The description provides extensive fan-out examples per classifier but does not explicitly state when not to use it.

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

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

Adds details beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format (paired data + citation URIs).

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?

Dense, single paragraph with every sentence adding value; examples like 'which is bigger' and 'head to head' clarify usage without 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?

Thoroughly explains input, behavior, and output despite no output schema; covers both entity types, ordering, and replaces multiple lookups.

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?

Expands on schema descriptions with examples (tickers/CIKs for company, drug names), behavior differences per type, and sorting logic, adding substantial meaning.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with specific examples like 'X vs Y' and 'compare these companies'.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and that it replaces 8-15 sequential lookups, providing clear context for when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical context: account requirement, paid plan for 'thorough' depth, return format (findings packet with gaps[]), expected duration (15-60s), and limitation for breaking news returning gaps. No contradiction.

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

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

Description is fairly long but well-structured: front-loaded with critical account requirement and alternative, then detailed explanation. Every sentence adds value, though minor redundancy could be trimmed. Still earns its length.

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

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

Given the tool's complexity (2 params, no output schema), the description is highly complete: covers purpose, usage guidelines, account requirements, return format, limitations, expected time, and behavioral context. Leaves 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% for both parameters. Description adds significant meaning: explains depth enum values (quick=3, standard=5, thorough=8) and mentions paid plan, clarifies that question can be broad/multi-part. 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?

Description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1160 STRUCTURED data sources' in one call, which is a specific verb+resource. It distinguishes from siblings like ask_pipeworx, which is for single lookups or breaking news.

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'. Provides alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and fallback 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 indicate read-only and idempotent. The description adds that it returns top-N tools with full schemas and curated examples, providing useful behavioral context beyond what annotations offer.

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

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

The description is three sentences, front-loaded with purpose. The list of domains is thorough but slightly lengthy. Still efficient and 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?

The description covers purpose, usage, return format, and parameter behavior. With no output schema, it compensates fully. Complete for a 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%, but the description adds examples and explains that query accepts natural language. It also notes the limit default and max, adding value beyond the basic schema.

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

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

The description clearly states the tool finds tools based on a description of data or task, listing many domains. It distinguishes from sibling tools as a meta-discovery tool, e.g., 'search_datasets' is more specific.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available' and explains what it returns. It could mention when not to use it, but the guidance is clear and helpful.

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

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

Discloses fan-out across SEC, XBRL, USPTO, news, GLEIF, returns specific fields, and notes soft-fail for patents. Annotations already declare safety, but description adds rich behavioral 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?

Single paragraph with example queries front-loaded. Dense but clear, no redundant 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?

No output schema, but description fully explains return fields (cik, filings, fundamentals, patents, news, LEI) and their sources, making it complete for agent understanding.

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 good descriptions. Description reinforces that type is 'company' only and value must be ticker or CIK, adding extra guidance on name resolution, which elevates it above baseline 3.

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

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

Description uses specific verbs like 'brief me on' and 'company profile for' and clearly states it provides a full cross-source profile of US public companies. It distinguishes from siblings like resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack...' and warns 'names not supported (use resolve_entity first)', giving clear when-to-use and 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 destructiveHint=true and idempotentHint=true. Description adds 'Delete' which aligns but does not provide additional behavioral context beyond what annotations convey. 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: first defines action, second provides usage context. No redundant information, efficiently 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?

Tool has one required parameter, no output schema, annotations present. Description covers purpose, usage timing, and sibling tools. Fully adequate for the tool's simplicity.

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

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

Schema covers the single 'key' parameter with description 'Memory key to delete'. Description adds no extra meaning beyond the schema. With 100% schema coverage, 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 'Delete a previously stored memory by key' which specifies the action and resource. The mention of 'remember' and 'recall' distinguishes it 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?

Explicitly tells when to use: when context is stale, task done, or clearing sensitive data. Also recommends pairing with remember and recall.

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 explains the tool's behavior: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. Annotations already indicate read-only, idempotent, non-destructive nature, and the description adds 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?

The description is concise: two sentences plus a brief bullet list of use cases. It is front-loaded with the core purpose and well-structured, with 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?

For a tool with 2 parameters, high annotation coverage, and no output schema, the description is complete. It covers what the tool does, the output format, and when to use it.

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

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

Schema description coverage is 100%, so the description adds no additional meaning beyond the schema. It implicitly confirms url is required and max_links is optional, but does not elaborate on format or constraints.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the target AI crawlers and the output format. It distinguishes itself from siblings by focusing on generating the file itself, not just 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 provides explicit use cases like getting a client's site indexed, drafting for own project, or auditing competitors. However, it does not explicitly state when not to use or mention alternatives, but the use cases are sufficient for guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the exact outputs: fields (name and type), geometry type, total record count, and capabilities. This goes beyond annotations to detail what the agent can expect, though it does not mention potential error conditions or network behavior.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource. It is concise with no redundant words, and every part adds value by listing the returned data types.

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

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

For a simple, single-parameter tool with no output schema and full annotation support, the description completely covers what the tool does and what it returns. No additional details about errors or edge cases are necessary given the read-only nature and clear schema 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?

The input schema fully describes the single parameter 'url' with a clear description and example. Since schema coverage is 100%, the tool description adds no extra semantic meaning beyond rephrasing. 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 uses a specific verb ('Get') and clearly identifies the resource ('ArcGIS Feature/Map Service layer's schema'). It enumerates the exact information returned (fields, geometry type, count, capabilities), making the tool's purpose distinct from sibling tools like query_layer, which would be used for querying features 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 implies usage when schema information is needed for a layer URL, but it does not explicitly state when to avoid this tool (e.g., when the user needs to query actual features) or suggest alternative tools like query_layer or search_datasets. The lack of explicit guidance means an agent might not clearly differentiate usage scenarios.

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

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

Annotations already declare readOnly and destructive hints. Description adds that it returns specific fields and is scoped to the caller's subscriptions, plus implies active-only default.

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 purpose and return fields, second gives usage guidance. No wasted words, 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?

No output schema, but description lists return fields. Annotations cover safety. All needed information for a simple list tool is present.

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

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

Schema has 100% coverage for the single parameter. Description adds context about 'active subscriptions' and caller scope, providing meaning beyond schema.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields. Distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit context: use to review monitoring before adding more or to find an id to cancel. Does not explicitly exclude other uses, but context is clear.

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

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

Description discloses rate limit (5 per identifier per day), that it's free and doesn't count against tool-call quota, and that team reads digests daily. Annotations are silent on these, so description adds significant value.

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 sentences), front-loaded with main purpose, and each sentence contributes 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?

Given 3 parameters (one nested object) and no output schema, description covers all needed aspects: purpose, usage, parameters, rate limits, cost, and team response. Complete for agent to use correctly.

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

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

Schema coverage is 100% with descriptions per parameter. Description adds extra guidance: 'don't paste end-user prompt', 'describe in terms of tools/packs', and message length suggestions. This goes beyond schema.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team, specifying types like bug, feature, data_gap, praise. It differentiates from siblings as no other tool serves a feedback purpose.

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

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

The description explicitly tells when to use each feedback type: bug (wrong/stale data), feature/data_gap (missing tool), praise (worked well). It provides clear scenarios for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds value by explaining the aggregation source (CF analytics-engine), privacy (no PII), and caching (5min-1h). 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?

Two paragraphs: first defines what it returns, second lists use cases and behavioral notes. Every sentence adds value; no fluff or repetition.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers purpose, use cases, parameter semantics, data source, privacy, and caching. It is fully complete 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 only parameter, window, is fully covered by schema (enum, description). Description adds behavioral insight: shorter windows surface what's hot, longer show steady-state demand. This adds meaning 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 returns top tools, packs, and call volume over a recent window. It specifies the verb 'returns' and the resource 'trending data from Pipeworx', and distinguishes from siblings by focusing on aggregated usage statistics.

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 choices, seeing alignment). Window selection guidance is given (shorter for hot, longer for steady-state). No explicit when-not-to-use, but the context makes it clear.

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

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

The description goes far beyond annotations by detailing the underlying algorithms (monotonicity violations, partition-sum checks, Jaccard similarity, placeholder filter), the fill check against CLOB depth, and the structure of the response. It fully discloses the tool's behavior and trade recommendations, consistent with readOnly and destructiveHint=false.

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

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

The description is long but well-structured: it front-loads the main purpose, then details modes, filters, response, and fill check. Every sentence adds value, though some sections are dense. It is appropriately sized for a complex tool.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains the response structure (opportunities[], partition_check, fill_check). It references the sibling tool for custom sizing and covers key behavioral details. Some specifics like data types are omitted but not critical for an AI agent.

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

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

Although schema coverage is 100% with basic descriptions, the main description adds significant semantic context: it explains the expected format for event slugs (e.g., 'fed-decision-may-2026'), that full URLs are accepted, and what kind of seed questions work for topic. This enhances understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using specific methods. It differentiates two modes (event and topic) but does not explicitly contrast with sibling tools like polymarket_edges or polymarket_edge_tracker, though fill_risk is referenced. The purpose is specific and actionable.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp ≤ 0), mentions the semantic anchor and partition filter, and references a sibling tool for custom sizing. This is comprehensive and clear.

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

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

The description extensively discloses behavior beyond annotations, including cache TTL (1h KV-level), response structure by_segment, edge derivation (edge_pp_net, kelly_fraction, slippage subtraction), and tradeable-edge filters. It aligns with annotations (readOnlyHint, idempotent) and adds critical context for safe invocation.

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 (nearly 400 words) but structurally front-loaded with purpose. Every sentence adds domain-specific detail, yet density may overwhelm agents. For a complex tool with 9 parameters and three model families, the length is justified but could be more streamlined.

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 (three model families, detailed edge calculation, eight parameters, no output schema), the description is remarkably complete. It covers response structure, filtering logic, diagnostic fields, and cache behavior, leaving no critical gaps for an agent to interpret outputs or understand failures.

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 meaningful context beyond schema descriptions, e.g., explaining why min_partition_leg_kelly exists (basket trades don't compose to single-leg Kelly) and how slippage_pp relates to Polymarket's fee structure. This extra guidance enriches parameter understanding.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price, aimed at agents discovering daily bets. It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx's disagreement signal, but does not explicitly contrast them.

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

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

The description explains when to use the tool (for finding 'what should I bet on today' opportunities) and provides practical knobs like min_liquidity and max_spread_pp. However, it does not mention when not to use it or contrast with alternative tools such as polymarket_arbitrage, leaving the agent to infer usage boundaries.

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. The description adds substantial behavioral context: return structure (tracked, expired, snapshot_dates), data sources (daily snapshots from polymarket_edges), and limits (60-day TTL, daily closes not intraday). No contradictions.

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

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

Description is front-loaded with key purpose and then details response format. Although slightly verbose, every sentence adds value given the lack of an output schema. Could be more concise by not repeating schema defaults.

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

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

Given no output schema, the description fully explains the return format (tracked, expired, snapshot_dates with all fields) and important caveats (TTL, daily closes). It is complete for a read-only data tool with two optional parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates defaults and clamps for 'days', and defaults for 'window', but adds minimal new meaning 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?

Description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge age and trend. It distinguishes itself from sibling tools by focusing on historical persistence rather than current edges.

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

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

The description explains when to use the tool (to evaluate edge age and trend) and implicitly contrasts fresh vs old edges. However, it does not explicitly name alternative tools or state when not to use it, leaving some ambiguity.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, forced_directional_risk, and warns about thin books and unhedged positions. No contradictions.

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

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

Well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loads purpose. Slightly verbose but every sentence adds value. Could be tightened without losing clarity.

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

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

No output schema, but description thoroughly details return fields for both modes, including verdict, capture_ratio, profit_usd, thin_legs, max_clean_notional, forced_directional_risk. Explains logic and risks. Complete given tool complexity.

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

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

Schema coverage is 100% with descriptions. The description adds beyond schema: explains side default behavior (auto for basket), size_usd interpretation as settlement notional for basket, clamp range 10-1,000,000, and which parameter is required based on mode.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth'. It distinguishes between single-market and basket modes with specific verbs like 'walks the ladder' and 'returns'. It also differentiates itself from siblings by naming when to use it over polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It explains why not to skip (partial basket fills convert arb into unhedged directional position) and mentions the dominant loss mode.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context beyond annotations, including compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and a candid note that real spreads are rarer than the shortcut list suggests. No contradictions.

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

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

The description is a single paragraph but structured with clear sections (purpose, modes, response, safety fields). It is front-loaded with the main purpose. However, it is verbose and could be more concise while retaining all necessary 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?

No output schema is provided, so the description must explain return values. It does: leg-by-leg prices, top_spreads_pp, safety fields like compatibility_warning, temporal_alignment, skipped counters. It covers key edge cases. However, it doesn't list all possible fields or their types, leaving some ambiguity for a complex tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds contextual semantics: topic parameter lists the 10 shortcuts, and explicitly explains that kalshi_event_ticker and polymarket_event_slug override the topic mapping. This goes beyond the schema but doesn't introduce entirely new concepts.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like 'polymarket_arbitrage' which focus on a single venue. The verb 'cross-venue spread' is specific and the resource is well-defined.

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

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

Explicitly describes two usage modes (topic shortcuts vs explicit tickers) and provides clear when-not-to-use guidance: warns about compatibility warnings, non-equivalent bet shapes, and temporal misalignment. States that most pre-mapped topics return warnings and are not tradeable.

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, safe behavior. Description adds return type (attribute rows and geometry) and SQL-like syntax, providing additional 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, first stating purpose and listing parameters, second giving sampling tip. Every sentence adds value, no redundancy.

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

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

Despite lacking output schema, the description covers return type (attributes/geometry), parameters with examples, and usage context. Adequate for a query tool with 6 parameters.

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

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

Schema coverage is 100% and description adds examples and context for parameters like where (SQL clause), out_fields (comma-separated), and order_by, going beyond schema definitions.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, specifying the action and resource. It distinguishes from sibling tools like search_datasets and layer_info by focusing on data retrieval.

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

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

Provides a concrete usage example ('where="1=1" + out_fields="*"') and implies URL comes from search_datasets. Lacks explicit when-not-to-use guidance, but context is clear.

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

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

Discloses scoping (by identifier) and the dual behavior (retrieve by key or list all). Does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint) and adds value beyond them.

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

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

Two sentences, front-loaded with the core action, no wasted words. Highly efficient and easy to parse.

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

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

For a simple tool with one optional parameter and no output schema, the description covers main behavior, scoping, and tool relationships. No gaps.

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

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

The description adds context beyond the input schema by referencing the 'remember' tool and providing example key types (ticker, address, notes). Schema coverage is 100%, so baseline is 3, but the extra usage context justifies a 4.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs and identifying the resource. It distinguishes from sibling tools 'remember' and 'forget' by mentioning pairing, and explains the scoping mechanism.

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?

Describes when to use the tool ('look up context... without re-deriving it') and mentions pairing with remember/forget, but does not explicitly exclude alternatives or state when not to use it.

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

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

Annotations declare readOnlyHint=true, but the description states mark_read:true flags events as read, which is a state modification. This is a direct contradiction, significantly reducing transparency.

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

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

Three sentences covering return format, parameter usage, and alternative access. No wasted words, front-loaded with key information.

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

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

Covers return fields, parameter effects, and alternative access. Lacks output schema, but description compensates well. Does not address pagination or error handling.

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

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

Schema has 100% coverage with descriptions, and the tool description adds value by providing an example for type ('sec_8k') and explaining the effect of mark_read on future calls.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on events rather than 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?

Provides clear context on filtering by type and since, and explains the mark_read parameter effect. Also mentions alternative access via HTTP endpoint. However, lacks explicit guidance on 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, idempotentHint, and destructiveHint=false. The description adds behavioral details beyond annotations: fan-out logic, fallback from GDELT to GNews, USPTO soft-fail status, and the fact that it makes 'one parallel call'. No contradictions.

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

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

The description is front-loaded with example queries and concisely lists sources and parameter behavior. Every sentence adds value, though slightly verbose due to including full example strings. Still well-structured and efficient.

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

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

No output schema, but the description explicitly states the return format (changes[] grouped by source, total_changes count, citation URIs). It covers behavior for multiple sources, fallback logic, and parameter constraints. Complex tool handled well.

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

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

Schema coverage is 100%, so baseline 3. The description adds usage context for `since` (ISO or relative, with example '30d'), but doesn't significantly enhance meaning for `type` or `value` beyond the schema. It meets the baseline requirement.

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 begins with concrete user queries, explicitly states 'change feed for a company in the last N days/weeks/months', and distinguishes from sibling tool entity_profile. It specifies the tool fans out to multiple sources (SEC, GDELT/GNews, USPTO), making the purpose unambiguous and differentiated.

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

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

The description provides explicit guidance: 'Use entity_profile instead when you want the static profile...' and gives parameter recommendations ('Use "30d" or "1m" for typical monitoring'). While it doesn't enumerate all when-not-to-use scenarios, the context 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 indicate idempotent and non-destructive, but the description adds critical behavioral context: persistence differences between authenticated (permanent) and anonymous (24-hour) sessions, and scoping by identifier. This goes beyond what annotations provide.

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

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

The description is four sentences, with the first sentence immediately stating the purpose. Every sentence adds value: use case, storage details, retention policy, and pairing with other tools. No superfluous words.

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

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

Given the tool has only 2 parameters, no nested objects, and no output schema, the description covers all necessary context: what it does, when to use it, persistence behavior, and relationship with siblings. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions for key and value. The description adds context by giving concrete examples (resolved ticker, target address) and explaining the key-value pair is scoped by user identifier, which is not in the schema.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using a key-value pair. It distinguishes itself from sibling tools 'recall' and 'forget' by explicitly mentioning them as partners.

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

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

The description explains when to use the tool: when discovering something worth carrying forward to avoid re-looking-up. It provides context on scope (scoped by identifier) and mentions alternatives (recall, forget). It doesn't explicitly list exclusions but the guidance is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups, which is useful for understanding latency. No contradictions.

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

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

The description is front-loaded with example queries and a clear purpose statement. It is fairly concise, though the list of example queries slightly overlaps with the purpose. 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 the complexity (two entity types, different outputs) and the presence of annotations and schema, the description is largely complete. It explains inputs, outputs, and internal behavior. Missing error handling details, but acceptable.

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 provides additional detail on return values for each entity type (e.g., ticker+CIK+company_name for company, RxCUI+ingredient+brand for drug), which is not captured in 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: resolving user-spoken names to canonical/official identifiers, with specific examples like ticker, CIK, and RxCUI. It distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides clear guidance on when to use the tool ('whenever you have a name but need an ID') and gives example queries. However, it lacks explicit exclusions or comparisons to specific sibling tools, though the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. No contradictions. Additional behavioral context beyond annotations is provided.

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

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

Two concise sentences, front-loaded with the core action (compare, probe, rank). Every sentence adds value. 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?

No output schema, but the description explains return fields (ranked list with score, confidence, signal density). Given good annotations and full schema coverage, the description is sufficiently complete for a comparative exploration 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 the schema already documents all parameters. The description adds minor context (e.g., first entity is the 'subject'), but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (likely different attributes).

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

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

The description explicitly states when to use: for competitive AI-marketing audits. It does not provide explicit when-not-to-use or alternatives, but the context of sibling tools offers differentiation. Clear context but lacks 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, and destructiveHint false. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s and will be listed in sources_failed if it times out, and the rest still returns. 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 fairly long but every sentence adds value. It is front-loaded with the core purpose and then provides details. Could be slightly more concise, but it remains readable and informative.

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

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

Given the complexity (composite tool, multiple data sources, partial failures), the description is complete. It explains the return structure (summary block, per-advisory detail, links, recent alternatives) and failure behavior. No output schema exists, so the description effectively covers what is returned.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that package is an npm package name (including scoped packages) and version defaults to latest. It also describes the return fields, which indirectly clarifies parameter usage. While the schema already has descriptions, the tool description provides additional context.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings by focusing on the npm ecosystem and the composite nature.

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

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

Explicitly provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also mentions ecosystem limitation (NPM only in v1) and fallback for other ecosystems, guiding when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which the description does not contradict. The description adds value by specifying the return fields (name, summary, record_count, owner/org, url) and the follow-up workflow, providing behavioral context beyond the annotations.

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

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

Two sentences with zero waste: the first sentence states purpose and scope, the second lists return values and provides actionable guidance. Front-loaded and efficient.

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

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

Given no output schema, the description adequately covers return fields. It also hints at integration with sibling tools. While it could mention pagination or error handling, the explanation is sufficient for a straightforward search tool with good annotation coverage.

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

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

With 100% schema description coverage, the baseline is 3. The description adds minor clarification such as 'keyword(s), e.g. parcels' for query and the optional nature of org_id, slightly improving usability. It does not add extensive new semantics, but it is adequate.

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

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

The description clearly states the tool searches Lincoln County GIS datasets by keyword, specifies the scope (parcels, addresses, zoning, public works), and distinguishes it from sibling tools like query_layer and layer_info by indicating it returns a url to be used with them.

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

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

The description explains when to use this tool (to search datasets) and provides clear guidance on the next steps by instructing to pass the returned url to query_layer or layer_info. It does not explicitly state when not to use it, but the context is sufficient for a focused 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?

Discloses embedding model (BGE-base-en), similarity (cosine), windowing (500-char overlapping), character limit (200K chars, truncated with flag), and that results include offsets for verification. Adds significant detail beyond annotations which already indicate safe, idempotent operation.

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

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

Description is front-loaded with key purpose and use case in first sentence, followed by supplementary details. Every sentence adds value; no redundancy.

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

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

Despite lacking output schema, description adequately explains return values (top-N passages with offsets and scores). Covers embedding details, character cap, and pairing advice. Sufficient for agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description provides examples for 'query' and restates limit behavior, but does not add substantial new 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 identifies the action (semantic search), resource (a fetched record text), and provides concrete examples (SEC 10-K, article). Differentiates from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly states when to use (record too large for prompt), pairs with sibling tool, and hints at alternatives (fetch+ground workflow). Provides clear context for appropriate invocation.

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

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

The description discloses behavioral traits such as requiring OAuth, phone verification, SMS cap, and the always-on feed. It does not contradict annotations. Annotations include idempotentHint:true, but the description does not contradict this.

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

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

The description is front-loaded with the core purpose and comprehensive without being verbose. Every sentence adds value.

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

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

Given the complexity (3 params, nested objects, no output schema), the description thoroughly explains subscription types, param formats, delivery options, and constraints.

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

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

Schema coverage is 100%, and the description adds detailed meanings and examples for each type's params and delivery channels, going beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It 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?

The description provides explicit guidance on when to use (proactive monitoring), prerequisites (Pipeworx OAuth account, verified phone for SMS), and supported types with examples. It implicitly indicates when not to use (anonymous/BYO accounts cannot persist).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that output includes tool+argument shapes from a live catalog, but doesn't detail data freshness or performance.

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?

Reasonably concise, front-loaded with purpose, categorizes output with dashes. Slightly wordy but each sentence adds value.

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

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

Despite no output schema, the description fully explains the return format (category-bucketed examples with tool shapes). Sufficient for an onboarding tool.

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

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

Schema coverage is 100% with clear description. The description enriches by showing how to use the topic parameter (e.g., 'pass topic to focus') and lists example values.

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

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

The description uses specific verbs like 'returns category-bucketed example questions' and clearly identifies it as the onboarding entry point, distinguishing it 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and provides guidance on when to use with arguments (omit or pass topic).

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 mutation (readOnlyHint=false) and idempotency. Description adds that the row is deactivated not deleted, and that historical events remain available. Adds meaningful context beyond annotations, though no mention of authentication or rate limits.

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

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

Two concise sentences: first states purpose and ownership, second explains behavioral outcome. No wasted words, 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?

Simple tool with 1 parameter and no output schema. Description covers ownership and deactivation behavior. Lacks explicit mention of return value but mutation tools often omit it; still adequate for 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?

Only parameter 'id' is described in schema as 'Subscription id (uuid) returned by subscribe.' The description does not add new semantic detail beyond the schema, and schema coverage is 100%, so baseline score of 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource, and differentiates from sibling tools like subscribe and list_subscriptions by implying cancellation action.

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?

Specifies ownership enforcement ('you can only cancel your own subscriptions'), providing a key usage constraint. Does not explicitly name alternatives or when-not to use, but the constraint implies the tool is not for others' 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 indicate read-only, idempotent, and non-destructive behavior. The description adds transparency about the output format (verdict types like 'confirmed' or 'refuted', actual value with pipeworx:// citation, percent delta) and notes that it replaces 4-6 calls, implying efficiency. It acknowledges version 1 limitations (supports company-financial claims) but could mention more constraints.

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

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

The description is a single paragraph of about six sentences, front-loaded with common query patterns. Every sentence adds distinct value: listing synonyms, stating usage, defining scope, listing returns, and highlighting efficiency. It is concise but slightly dense; a bulleted list could improve readability.

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

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

Given the tool has only one parameter and no output schema, the description covers almost all necessary context: input format, domain, process, output types (verdict categories, citation, delta), and value proposition. It effectively compensates for the lack of an output schema by detailing the return values.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing concrete examples ('Apple's FY2024 revenue was $400 billion') and explaining what constitutes a natural-language claim, which helps the agent format inputs correctly beyond the schema's brief description.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims, providing specific query patterns like 'Is it true that…' and 'fact check'. It distinguishes itself from sibling tools by noting it replaces multiple sequential calls and is specialized for company-financial claims via SEC EDGAR and XBRL.

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

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

The description explicitly states to use the tool 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the current scope (company-financial claims) but does not explicitly exclude other factual claims or name alternative tools for out-of-scope queries.

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