NYC Open Data

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds context that the tool probes multiple models, requires API key for Anthropic, and returns per-model results. 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 well-structured with front-loaded action ('Probe...'), clear parameter explanations, and use-case context. Could be slightly tighter, but every sentence adds value.

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

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

Despite no output schema, description covers return format (per-model score, confidence, signals, raw_response + combined view) and use cases. Could mention rate limits or cost, but sufficiently complete for this moderate-complexity tool.

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

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

Schema description coverage is 100%, but description adds significant meaning: explains 'entity' with examples ('Pipeworx'), clarifies 'models' defaults, details '_apiKey' as pass-through to Anthropic, and gives 'context' usage for disambiguation. Adds value beyond schema.

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

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

The description uses specific verbs ('probe', 'score') and clearly defines the resource: 'LLMs for what they know about a business / brand / product / topic'. It distinguishes from siblings like 'compare_entities' and 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides default model vs optional BYO key. Could improve by explicitly mentioning when not to use or alternative siblings, but current 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns structured answers with stable pipeworx:// citation URIs and is a single fast call. It does not contradict annotations but could elaborate on limitations or edge cases.

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

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

The description is relatively long but well-structured: front-loaded with a strong prefer-over statement, followed by detailed use cases and examples. Every sentence adds value, though some redundancy exists (e.g., listing domains twice). Minor trimming could improve conciseness.

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

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

Given no output schema, the description explains return format (structured answer with citation URIs). It covers the tool's role in the ecosystem, mentions tier compatibility, and provides a complete picture for a complex tool with many sources. No gaps remain.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question', each with a description. The description adds minimal value beyond the schema—just mentions 'fills arguments'—so a baseline 3 is appropriate.

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

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

The description clearly specifies that ask_pipeworx routes factual questions to 4,774 tools across 1,242 sources for authoritative structured data, listing many domains (SEC filings, FDA, FRED, etc.). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, earning a high score.

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

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

Explicitly instructs to prefer over web search for factual queries, provides detailed when-to-use guidance with example queries ('what is', 'look up'), and specifies when to step up to alternatives. This covers both inclusion and exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description reveals the extraction behavior and refusal reasons (not_in_source, no_tool_match, etc.), which are critical for an agent to understand how the tool behaves on failure. No contradiction with annotations.

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

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

The description is front-loaded with the most important info: 'Hallucination-resistant answer mode' and then explains routing, extraction, return format, and usage. While slightly lengthy, every sentence adds value and there is 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 an output schema, the description defines the return format in detail: fields like answer, evidence, confidence, source, fetched_at, and explicit refusal reasons. It also explains routing and cost. Given the tool's complexity, this is thorough.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the question. The description adds no additional meaning beyond the schema's descriptions. Baseline 3 is appropriate since the schema carries the full load.

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 a 'hallucination-resistant answer mode for high-stakes reads' and specifies it EXTRACTS the answer using ONLY the tool result. This distinguishes it from sibling 'ask_pipeworx' which presumably does not perform extraction. The verb 'extracts' and resource 'answer' are 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides a clear exclusion: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off ('costs one extra LLM call'). This is exemplary guidance.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds extensive behavioral details: resolution logic, fan-out patterns, safety short-circuits, spread warnings, and cancellation rule risks. No contradiction with annotations.

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

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

The description is very long and dense, lacking conciseness. While all information is relevant, it could be organized more efficiently.

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 fan-out scenarios, response shapes, edge cases), the description is thorough and covers all necessary context for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and the description enhances each parameter: market input formats, depth options, and include_raw behavior. Adds meaning beyond schema types.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific input examples and output structures. It distinguishes itself from siblings by detailing unique fan-out and classification mechanics.

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 (e.g., 'should I bet on X') and provides examples. Does not explicitly list when not to use, but the 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?

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant behavioral context: sorted by primary metric for 'largest' reads off top; handles off-calendar fiscal years correctly; returns paired data + citation URIs. No contradiction with annotations.

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

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

Single concise paragraph, well-structured with examples, type-specific detail, and usage recommendation. Every sentence adds unique value with no redundancy.

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

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

Given 2 params and no output schema, description thoroughly explains expected output (paired data, citation URIs) and edge cases (off-calendar fiscal years). Minor gap: no explicit error handling, but overall complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds meaningful context: type explains data pulled per entity (company: 10-K metrics; drug: adverse events, approvals, trials); values specifies format (tickers/CIKs for company, drug names) and bounds (2-5). Exceeds baseline 3 for high coverage.

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

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

Description clearly states it compares 2-5 companies or drugs side-by-side. Lists explicit use-case phrases like 'X vs Y', 'which is bigger', 'rank these companies'. Distinguishes from sequential single-pack lookups, stating it replaces 8-15 calls.

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

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

Explicit instruction 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides specific trigger phrases (e.g., 'X vs Y', 'rank these companies'). Implicitly excludes non-comparison scenarios. Strong guidance on 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=true, idempotentHint=true, destructiveHint=false, so the description's disclosure of behavior (searching, returning specific fields) adds context. It reveals the exact return fields and hints at a follow-up action, providing value beyond the annotations.

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

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

The description is two sentences, very concise with no fluff. It front-loads the action and includes all essential information. Every sentence adds value.

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

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

Despite lacking an output schema, the description fully specifies what is returned (resource_id, name, description, category, update date). It also explains the purpose (search a catalog) and suggests a follow-up tool. Given the tool's simplicity and clear annotations, this is complete.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The overall description adds minimal extra meaning; it reiterates that the query is a 'keyword' and that limit/offset control pagination, but these are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Search' and the resource 'NYC Open Data catalog of open datasets'. It specifies the return fields (resource_id, name, description, category, update date) and distinguishes this tool from siblings by focusing on dataset discovery, while sibling tools like 'query' and 'metadata' are suggested for subsequent steps.

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 (searching by keyword) and what to do with the results (pass resource_id to query/metadata), providing clear next steps. It implies a workflow, though it doesn't explicitly state when not to use it or compare to all siblings. This is adequate for usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: parallel decomposition across 4,774 tools, output format (evidence, confidence, source, citation, gaps), non-open-web nature, expected time (15-60s). 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?

Every sentence adds value: account requirement first, then core function, usage guidance, output format, and timing. No fluff, well-organized, front-loaded with critical prerequisites.

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

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

Despite no output schema, description fully explains return format (findings packet with evidence, confidence, source, citation, gaps). Covers expected timing, data sources, and parameter effects. Comprehensive for a tool with only 2 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 covers both parameters with 100% descriptive coverage (question as natural language, depth enum with count meanings). Description adds context: depth requires paid plan for 'thorough', and tool automatically decomposes questions. Marginal but useful addition.

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

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

The description clearly states the tool performs "grounded multi-source research" across 1242 structured data sources, distinguishes it from open-web search, and contrasts with sibling tools (ask_pipeworx) for single lookups and 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 explains when to use (broad/multi-part questions over structured data) and when to use alternatives (single lookup → ask_pipeworx, breaking news → ask_pipeworx). Also notes account requirements and depth constraints.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which match the description's implication of a safe, non-destructive search. The description adds that results include full input schemas and are ready to call directly, providing behavioral details beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose. It includes a list of example domains which is helpful but slightly verbose. Overall, it is 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?

Despite lacking an output schema, the description fully explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also notes that results are ready to call directly. For a search/discovery tool, this is complete and actionable.

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

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

Schema description coverage is 100%, with each parameter described. The description adds value by clarifying that 'query' accepts aliases (task, q, description, search) and that it expects a natural language description. This enriches the schema but does not introduce entirely new information.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and explains the return value: top-N tools with full schemas. This distinguishes it from siblings like 'query' or 'search_within' which operate on data, not tool discovery.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear usage context, though it does not mention specific alternatives or when not to use it.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: it fans out across multiple sources, explains each source's data, mentions the USPTO soft-fail after May 2025, and specifies CIK/ticker requirements. 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 moderately long but well-structured with example queries upfront, functional description, and details on each data source. Every sentence adds value, though slight trimming could improve conciseness.

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

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

Given the tool's complexity (multiple data sources, soft-fail, no output schema), the description covers all essential aspects: what it returns, how it fans out, limitations, and usage patterns. It is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that 'type' must be 'company' (the only enum value) and that 'value' accepts ticker or CIK with examples, plus explicitly states names are not supported.

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

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

The description clearly states the action (return a full cross-source profile) and the resource (US public company). It distinguishes itself from sibling tools like resolve_entity by specifying what it does not do (names not supported).

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 to prefer this tool over chaining multiple single-pack lookups for a holistic view, and directs users to resolve_entity if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context about clearing sensitive data, which is useful beyond annotations, but does not mention idempotency explicitly. No contradiction.

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

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

Three focused sentences: action, use cases, and companion hints. No fluff, highly efficient.

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

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

Given the simple single-parameter schema, no output schema, and annotations covering safety, the description fully covers what an agent needs: purpose, usage, and behavior.

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

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

Schema coverage is 100% with clear parameter description 'Memory key to delete'. The description adds minimal value beyond that, so baseline 3 is appropriate.

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

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

The description clearly states the action 'Delete a previously stored memory by key', specifying the verb, resource, and method. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests alternatives/companion tools, giving clear usage 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 aligns with annotations (readOnlyHint, non-destructive) and adds behavioral details: fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. It provides transparency beyond annotations by explaining the process.

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, with a clear first sentence stating the main purpose, followed by succinct details and a bullet-like list of use cases. Every sentence contributes value without fluff.

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

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

Given the tool's simplicity (2 params, no output schema, comprehensive annotations), the description covers all necessary aspects: what it does, how it works, output format, and use cases. It is fully complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds minimal extra meaning, only repeating the default and max for max_links. It 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'URL', and the output format. It distinguishes itself from sibling tools like 'ai_visibility_check' by focusing on llms.txt generation.

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 (indexing a client's site, drafting for own project, auditing competitors), giving clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds the specific fields returned and default filtering (active subscriptions only), but these are moderate additions 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 concise sentences, front-loaded with action and return fields, followed by usage guidance. 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?

For a simple list tool with one optional parameter, the description covers what the tool returns and provides usage context. No output schema is needed as return fields are listed.

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

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

Schema coverage is 100% with one parameter (include_inactive) fully described. The description does not add extra meaning about the parameter, meeting the baseline expectation.

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 the tool lists the caller's active subscriptions, specifies return fields, and differentiates from sibling tools like subscribe and unsubscribe by mentioning its use for reviewing before adding or finding an id to cancel.

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

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

Provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly mention when not to use, but the context is clear and sufficient for an AI agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by listing the metadata fields returned, but does not add further behavioral details beyond what annotations provide.

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

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

The description is a single, well-structured sentence. Every word is meaningful and there is no superfluous 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?

For a tool with one parameter and full annotation coverage, the description is complete. It explains what the tool returns, filling the gap of no output schema.

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

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

Schema coverage is 100% and the schema describes the parameter. The description adds an explicit example ('8wbx-tsch'), which increases clarity beyond the schema alone.

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

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

The description clearly states the tool gets a dataset's schema and metadata (columns, types, row count, etc.) by resource_id, with an example. It distinguishes itself from sibling tools like 'datasets' which likely lists available datasets.

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 makes it clear when to use this tool (when you need schema and metadata for a specific dataset). It doesn't explicitly state when not to use it, but the context is clear given no direct alternatives.

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

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

The description adds behavioral traits beyond annotations: rate-limited to 5 per identifier per day, doesn't count against tool-call quota, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is a single paragraph but is tightly written with no extraneous information. Every sentence adds value, and key points are front-loaded (purpose, then usage guidelines, then behavioral details).

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

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

For a feedback tool with 3 parameters, no output schema, the description covers input requirements, usage examples, rate limits, and behavioral expectations completely. It is 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%, so baseline is 3. The description adds value by explaining each enum value for 'type' and clarifying the purpose of 'context' and 'message' parameters, enhancing understanding 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 explicitly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It clearly differentiates from siblings, as no other tool serves this feedback function.

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

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

The description provides explicit guidance on when to use the tool (bugs, missing features, data gaps, praise) and what not to do (don't paste end-user prompt, describe in terms of tools/packs). It also mentions rate limits and that it's free.

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, and non-destructive behavior. The description adds transparency about the data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). This goes beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded with the core purpose. Each sentence adds value: the initial sentence defines the output, the bulleted list provides use cases, and the final sentences clarify data handling and caching. No fluff.

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

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

Given the simplicity (one optional param, no output schema), the description covers the tool's purpose, parameters, use cases, data source, and caching. However, it could be more complete by describing the exact return format (e.g., JSON structure), especially since there is no output schema.

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

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

The single parameter 'window' is fully described with enum values and a schema description that also explains the effect (shorter windows for current hotness, longer for steady-state). The description adds semantic context about the trade-offs, which goes beyond the raw 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 verb 'Returns' and the resource 'top tools, top packs, and total call volume.' It specifies the windows and distinguishes this tool from siblings by focusing on trending data aggregated from other AI agents' calls, which is unique among the listed siblings.

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

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

Three explicit use cases are provided: discovering hot data sources for current events, confirming a popular tool is canonical, and seeing alignment with use case. While it doesn't explicitly state when not to use or list alternatives, the use cases give clear guidance on when this tool is appropriate.

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

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

Annotations indicate readOnlyHint true, openWorldHint true, idempotentHint true, destructiveHint false, which already signal safe, non-destructive behavior. The description adds valuable behavioral context: it explains the scanning algorithm, Jaccard similarity threshold (0.30), partition filter for placeholder slugs, and the fill check that verifies against live order book depth. No contradictions with annotations.

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

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

The description is moderately long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, etc.). It front-loads the core purpose and modes, then provides necessary details. While every sentence adds value, some might be considered slightly verbose, but overall it maintains good efficiency.

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

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

Given the tool's complexity (multiple modes, algorithmic checks, return values), the description is remarkably complete. It explains the output structure (opportunities[], partition_check, fill check details), constraints (Jaccard similarity, placeholder filter), and even warns about realizable edge vs theoretical edge. Without an output schema, the description fully compensates by detailing the response format.

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

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

Schema coverage is 100%, with descriptions for both parameters (event and topic). The description significantly expands on the schema by explaining how each parameter is used: event accepts slugs or full URLs, topic is a seed question for cross-event scanning. It also clarifies the recommended usage (event for specific market). This adds substantial meaning beyond the schema's brief descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between three modes: no-args trending scan, event mode for single markets, and topic mode for cross-event scans. The verb 'find' combined with specific technical mechanisms makes the purpose precise and unambiguous.

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

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

The description explicitly guides when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It explains the rationale behind each mode, though it does not explicitly state when not to use the tool or mention alternatives among siblings.

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

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

The description extensively discloses behavioral traits: caching policy (1h at KV level), response structure (by_segment with model_driven, structural_arbitrage, concentrated_longshot), edge computation details (edge_pp_net, Kelly fractions, slippage), and diagnostics. This goes well beyond the annotations which already indicate readOnly, idempotent, and nondestructive.

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

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

The description is well-structured with clear sections (segments, knobs, response top-level) and front-loads the core purpose. However, it is verbose, containing detailed model specifications (e.g., 'per-sport α (tennis 1.02, soccer 1.10, MMA 1.15)') that could be omitted for conciseness.

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

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

Given no output schema, the description fully explains the response structure including by_segment segments, diagnostics, and fed_candidates. It also covers caching, parameter behavior, and tradeable-edge filters, making it self-contained for an agent to understand and invoke correctly.

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

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

With 100% schema description coverage, the description still adds significant value by explaining parameter nuances (e.g., slippage_pp: 'Polymarket has zero trading fees...', min_partition_leg_kelly: 'Partition arbs always return kelly_fraction_half=0...'). It provides practical guidance on defaults and typical values.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly frames it as 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage by focusing on general opportunity discovery.

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

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

The description provides a clear use case ('built for what should I bet on today') and explains how to filter with knobs like min_liquidity, max_spread_pp, and category_filter. However, it does not explicitly state when to avoid this tool in favor of siblings like polymarket_arbitrage or polymarket_edge_tracker, 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant value: explains the data source (daily snapshots), the response structure (tracked[], expired[], snapshot_dates[]), derived fields (first_seen, trend, decay_pp_per_day), and caveats (gaps mean no scan, decay computed on 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?

The description is content-rich and front-loaded with purpose. However, with around 150 words, it is somewhat lengthy. Some technical details (e.g., 'net of default slippage') could be considered secondary. Still, every sentence serves a purpose, and the structure is logical.

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

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

The tool has no output schema, so the description fully explains return fields: tracked[], expired[], snapshot_dates[]. It details important sub-fields (first_seen, trend, decay_pp_per_day) and limitations (history depth, TTL). Given the complexity and sibling context, the description is complete.

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

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

Schema coverage is 100% and both parameters are described. The description adds practical meaning: 'days (lookback, default 14, max 30)' explains clamping beyond schema, and 'window (snapshot family, default 1wk)' clarifies the concept of snapshot families, which is important for agent 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 uses specific verbs ('tracks', 'answers') and clearly identifies the resource ('edge persistence and decay telemetry from daily polymarket_edges snapshots'). It distinguishes itself from siblings by focusing on temporal analysis versus raw snapshots, and explicitly contrasts a fresh edge with a 3-week-old edge.

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

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

The description states when to use this tool: to answer 'how long has this edge existed and is it shrinking?' It provides context (old vs. new edges) and mentions LIMITS (history depth, TTL). No explicit when-not-to-use, but the purpose is well-defined.

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 a safe read-only, idempotent operation. The description goes far beyond by explaining how it walks the order book ladder, returns verdicts like clean/degraded/cannot_fill, and details basket behavior including thin_legs and forced directional risk. No contradictions with annotations.

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

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

Well-structured with sections for single-market and basket modes, and front-loaded with the main purpose. While somewhat verbose, each sentence adds value. Could be slightly tighter but remains effective.

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

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

Despite no output schema, the description thoroughly explains return values (top_of_book, vwap_fill_price, etc.) and covers edge cases like partial fills and unhedged directional risk. Complete for the tool's intended use.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains default side auto for basket, size_usd interpretation (max spend vs target proceeds vs settlement notional), and clarifies that market or event is required. This adds value beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific outputs like top_of_book, vwap_fill_price, etc., making the purpose unambiguous.

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

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

Explicitly instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about partial baskets leading to unhedged directional risk. Provides clear context for when to use this tool versus alternatives.

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

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

The description goes far beyond annotations by detailing response structure (leg-by-leg prices, top spreads), safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and interpreting real spreads. It clearly explains behavioral traits like non-equivalent bet shapes and temporal misalignment. No contradiction with readOnlyHint or other annotations.

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

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

The description is well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is somewhat lengthy but every sentence provides valuable information. Could be slightly tighter, but overall effective.

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

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

Given the lack of output schema, the description compensates fully by explaining the response structure, safety fields, and interpretation of spreads. It addresses complexity of cross-venue comparisons and potential pitfalls, making the tool's behavior predictable for an agent.

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

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

The input schema has 100% description coverage, but the description adds rich semantics: examples, enumeration of topic values, explanation of how explicit parameters override topic, and context about pre-mapped macros. This adds significant meaning beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons. The two modes (topic shortcuts and explicit pairings) are explicitly defined.

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

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

The description explains when to use topic mode vs explicit mode and warns that pre-mapped topics often yield compatibility warnings. It provides context for interpreting results but does not explicitly contrast with alternatives or specify when not to use the tool.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior; the description adds that it returns JSON and notes a default limit of 1000 rows, providing useful 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?

The description is a single sentence that efficiently states the purpose, resource, and core usage rules, with 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 the moderate complexity (7 params, 1 required) and absence of output schema, the description adequately explains how to construct queries and the return format, though it could mention pagination via offset for completeness.

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

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

With 100% schema coverage, the description adds value by clarifying that SoQL clauses should be provided without the leading '$' and mentioning the default limit, which aids correct parameter usage.

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

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

The description clearly states it runs a Socrata SoQL query against a NYC Open Data dataset by resource_id, distinguishing it from sibling tools like 'datasets' which list available datasets.

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 the query syntax and parameters (where, select, group, order without leading $, plus limit/offset), but does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds context about scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which is useful. 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?

Three succinct sentences, front-loaded with the core purpose. Every sentence adds value with 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?

For a simple read-only key-value retrieval tool with one optional parameter and clear annotations, the description covers all needed context. No output schema required as return format is obvious.

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's parameter guidance ('omit the key argument to list all keys') is a verbatim repeat of the schema description. No additional meaning added beyond what the schema already provides.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. Verb and resource are specific and the behavior is distinguished from siblings like remember and forget.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and mentions scoping. It pairs with remember/forget but does not explicitly state when not to use it or list alternatives beyond those.

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 valuable context: the format of returned alerts (source, citation_uri, raw payload), the effect of mark_read on state (flagging as read), and the equivalence with an HTTP endpoint. No contradictions with annotations are evident in the description itself, but the mark_read parameter implies a mutation that conflicts with readOnlyHint=true, but that is a schema/annotation issue, not a description issue. The description accurately describes the 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 concise (4 sentences), front-loaded with purpose, and every sentence adds useful information without redundancy. It is well-structured 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?

Given the tool has 5 optional parameters, no output schema, and good annotations, the description covers the return format, filtering options, mark_read behavior, and alternative endpoint. It lacks explicit mention of the limit parameter's default or unread_only behavior, but the schema descriptions suffice. Overall, it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by giving an example for type ('sec_8k'), reinforcing the ISO timestamp format for since, and explaining the mark_read parameter's effect. It does not elaborate on unread_only or limit but the schema already covers those.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb (pull) and resource (subscription feed alerts). It specifies that the tool returns recent alerts with source, citation_uri, and raw event payload, distinguishing it from sibling tools like list_subscriptions or recent_changes.

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 filtering by type with an example ('sec_8k') and by since with ISO timestamp, and explains the mark_read parameter's effect. It also mentions that polling works and provides an alternative HTTP endpoint. However, it does not explicitly exclude alternatives or compare with sibling tools.

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

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

Annotations already indicate read-only, non-destructive behavior. The description adds significant detail: fans out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic, USPTO soft-failure, and return structure (grouped changes, total count, citation URIs). No contradiction.

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

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

The description is a single dense paragraph with good front-loading of example queries. It is clear and every sentence adds value, but could benefit from structural improvements like bullet points for 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?

No output schema exists, but the description fully covers return structure (changes grouped by source, total_changes, citation URIs) and edge cases (USPTO soft-fails). For a 3-parameter tool, this is complete and 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 description coverage is 100%. The description adds extra context: relative shorthand examples (e.g., '7d', '30d'), recommendation for monitoring, and explanation of value (ticker or CIK). This goes beyond the schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a time window, using example queries. It distinguishes itself from the sibling tool entity_profile by specifying that entity_profile is for static profiles.

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 (e.g., 'what's new with X') and explicitly contrasts with entity_profile for static profiles. It provides recommended relative time values like '30d' or '1m', but does not fully elaborate all when-not-to-use scenarios.

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

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

Describes persistence differences between authenticated and anonymous sessions, and key scoping, going well beyond annotations which lack these details.

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?

Every sentence adds value; purpose, usage, behavior, and pairing are all included in a concise paragraph without redundancy.

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

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

Given the simple key-value nature, the description covers all needed context: purpose, usage, storage details, and related tools. No output schema needed.

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

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

Schema coverage is 100%, description adds examples and clarification that value can be any text, but parameter descriptions in schema are already clear.

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 explicitly states saving data for later reuse, specifies key-value pair storage, and distinguishes from sibling tools recall and forget.

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

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

Clearly explains when to use (when discovering information worth carrying forward) and mentions pairing with recall/forget, but lacks explicit when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool cascades through several lookup endpoints internally and replaces 2-3 manual lookups, giving useful behavioral context beyond the annotations.

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

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

The description is front-loaded with example queries and then states purpose and details. It is somewhat lengthy but each sentence adds value. Could be slightly more concise, but structure is good.

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 explains what each type returns (ticker+CIK+company_name+citation URI for company; RxCUI+ingredient+brand+citation for drug). It also mentions cascading behavior. For a two-parameter lookup tool, this is very complete.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds meaning by explaining accepted formats for 'value' (ticker, CIK, name; brand or generic) and describing the enum in 'type' with return details.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier. It provides specific examples ('What's the ticker for...') and distinguishes from siblings by indicating it should be used first when 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 explicitly says 'Use FIRST whenever you have a name but need an ID' and gives examples of when to use it. It does not state when not to use, but the context is clear enough given the diversity of sibling tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds process details (probes, ranks, surfaces) which goes beyond annotations and helps the agent understand the behavioral flow.

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

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

Three sentences front-loaded with purpose, includes a concrete example, and no redundant information. Every sentence earns its place.

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

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

Despite no output schema, the description specifies the output format (ranked list with score, confidence, signal density). For a tool with 4 parameters and clear annotations, the description is sufficiently complete.

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

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

Schema description coverage is 100%, but the description adds context about the 'entities' parameter: the first entry is treated as the subject. This nuance is not in the schema, providing extra value for 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 compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, and produces a ranked list. It distinguishes itself from the sibling ai_visibility_check (single entity) by emphasizing multi-entity comparison.

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

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

Description explicitly frames the tool for competitive AI-marketing audits with an example question. It implies ai_visibility_check as the single-entity alternative by mentioning it is used per entity, but does not explicitly say 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out across two services, mentions partial graceful degradation, and warns about bundlephobia timing (5-30s). No contradictions with annotations.

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

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

The description is relatively long but every sentence adds value. It is front-loaded with the core purpose. However, it could be slightly more concise by structuring as bullet points or reducing redundancy. Still, it is efficient given the complexity.

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

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

Despite lacking an output schema, the description thoroughly covers the return structure (summary block, per-advisory detail, links, alternatives) and edge cases (partial failures, scoped packages). It is complete for a tool of this complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds value by explaining that 'version' defaults to latest and that scoped packages (e.g., '@types/node') are accepted. This provides practical context 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 identifies the tool as a composite check for evaluating npm packages, combining deps.dev and bundlephobia. It specifies the exact outcome ('is X safe / popular / small') and differentiates from siblings by limiting scope to NPM and mentioning other ecosystems fall under a different tool.

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 ('is X safe / popular / small') and includes limitations (NPM only v1, partial failures). It also provides a concrete example ('what does adding lodash cost me'). The description gives clear guidance on when not to use (other ecosystems) and how the tool handles failures.

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

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

Annotations provide readOnly, openWorld, idempotent hints, but description adds significant context: embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K chars with truncation and flagging), and output details (offsets for verification). No contradiction with annotations.

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

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

Four sentences, each earning its place: purpose, use case, pairing, technical details. Front-loaded with essential functionality, no filler.

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

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

For a tool with 3 params and no output schema, description explains output format (passages with offsets and scores), limits (200K chars), truncation behavior, and pairing with sibling. Adequate for agent invocation.

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

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

Schema coverage is 100% with clear parameter descriptions. Description reinforces and adds context: examples for text (SEC 10-K body) and query (e.g., 'supply-chain risk'), and clarifies default for limit. Provides marginal added value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It uses specific verb+resource ('Semantic search INSIDE a fetched record') and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document approaches.

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: 'Use when the record is too big to cram into the prompt — search_within saves context.' Also provides alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds context on OAuth requirement, rate limits (10 SMS/day), auto-disable for webhooks after 10 consecutive failures, and one-time webhook secret. Does not clarify if duplicate subscriptions are allowed or if subscription can be updated, but covers key behavioral traits 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?

Description is front-loaded with the primary action and returns value. Contains detailed examples and constraints, which are valuable. Slightly lengthy but each sentence adds 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 exists, but description states it returns the subscription ID. Covers required OAuth, all delivery options with constraints, and type-specific params. Lacks error response details or behavior on duplicate subscriptions, but for a 3-param tool with high schema coverage, it is adequately complete.

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

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

Schema coverage is 100%. Description adds substantial meaning with concrete examples for each subscription type (e.g., sec_8k with items array, fred_series with series_id) and delivery channels, including webhook HMAC details. The params object's description clarifies requirements like 'sponsor or condition required' for clinical_trial.

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

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

Description clearly states it creates a subscription to live-data event streams, returns a subscription ID. Lists specific types (sec_8k, polymarket_edge, etc.) and delivery channels, distinguishing it from siblings 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?

Explicitly requires a Pipeworx OAuth account and notes anonymous/BYO cannot persist. Provides detailed guidance on when to use each subscription type (e.g., sec_8k for filing updates, polymarket_edge for cross-venue mispricings). Does not explicitly state when not to use or provide alternatives to this tool, but the 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns example questions with exact tool calls from a live catalog, but does not explicitly state it's a read-only operation. 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 somewhat long but well-structured and front-loaded with alternative user queries. Each sentence has value, though minor trimming could improve conciseness.

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

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

Given no output schema but full annotations, the description fully explains the tool's output structure (category-bucketed questions with tool calls), its use cases, and when to employ 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 coverage is 100% for the single parameter 'topic'. The description adds meaning by listing example values and explaining the behavior when omitted, going beyond the schema.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions. It distinguishes itself from sibling tools by specifying it should be used first when unfamiliar with Pipeworx.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic vs. omit 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?

The description goes beyond the annotations by detailing that the row is deactivated (not deleted) and that historical events remain accessible via 'recent_alerts'. The annotations already indicate idempotence and non-destructiveness, and the description adds useful behavioral nuance without any contradiction.

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

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

The description is concise with only two sentences. The first sentence immediately conveys the core action, and the second adds crucial behavioral context. Every sentence serves a purpose with no redundancy.

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

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

Given the simplicity of the tool (one parameter, no output schema, and comprehensive annotations), the description is complete. It explains the outcome (deactivation), ownership constraint, and the impact on historical data, leaving 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?

The input schema already provides a description for the 'id' parameter, and the description merely references 'by id' without adding new semantic information. Since schema coverage is 100%, the baseline is 3, and the description does not further enhance 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 action 'Cancel a subscription by id' using a specific verb and resource, and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by noting that the row is deactivated, not deleted, which sets it apart.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or suggest alternatives, keeping it from a perfect score.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context on the return value (verdict types, citation, delta) and the underlying data source (SEC EDGAR + XBRL). No contradictions; the description enriches the understanding 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 a single paragraph but front-loaded with examples. Every sentence adds value: examples, use case, supported domain, replacement benefit. Slightly verbose with multiple examples, but still efficient for the information conveyed.

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

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

Given the complexity of claim verification and no output schema, the description adequately explains the return verdicts (confirmed, approximately_correct, etc.) and the structured form. It could mention limitations (only public US companies) but is generally complete for agent decision-making.

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

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

With only one parameter and 100% schema description coverage, the baseline is 3. The description enhances the schema by providing natural-language examples of claims (e.g., 'Apple's FY2024 revenue was $400 billion') and explaining the output structure, which adds meaning beyond the schema alone.

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

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

The description starts with natural-language examples like 'Is it true that…' and 'fact check', clearly indicating it's for claim verification. It specifies support for company-financial claims via SEC EDGAR + XBRL, distinguishing it from siblings like deep_research or entity_profile. The verb 'validate' combined with the resource 'claim' is specific and unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and notes it replaces 4–6 sequential calls. It does not provide explicit when-not-to-use scenarios or mention alternative tools, but the context is clear enough for appropriate selection.

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