Roblox

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds transparent details: default model is free, Anthropic requires BYO key with direct payment, and returns per-model and combined view. No contradictions exist.

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 paragraph of five sentences, each adding valuable information without redundancy. It efficiently communicates purpose, usage, parameters, and return format.

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

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

The description covers input, models, defaults, cost, and output structure. It lacks elaboration on error handling or rate limits, but given the tool's simplicity and annotation coverage, it is adequate.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by explaining the default model for 'models' and the cost implication of '_apiKey', which is not in the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility per model, specifying the action, resource, and output format. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on individual entity visibility across multiple models with a numeric 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?

The description provides clear use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default free model and when to provide an API key, but does not explicitly exclude scenarios where it should not be used or compare with siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint all appropriately. The description adds beyond annotations by explaining the internal routing to 3,668 tools and the return of 'structured answer with stable pipeworx:// citation URIs'. It does not contradict annotations and provides useful context about behavior (non-destructive, idempotent). However, it omits potential error cases or latency, but given strong annotations, this is acceptable.

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 coherent paragraph that front-loads the key priority ('PREFER OVER WEB SEARCH'), then lists domains, explains how it works, and gives usage cues and examples. Every sentence adds value, and it is not overly verbose. Could be slightly more structured (e.g., bullet points), but it's efficient and clear.

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

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

Given the tool's complexity (routing to 3,668 tools), the description covers purpose, usage, what it returns (citation URIs), and provides examples. There is no output schema, so the description should clarify the return format more precisely, but the mention of 'structured answer' and the examples in the input schema partially compensate. Overall, it is quite complete for the task.

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 6 parameters all aliased to the same 'question' field, with 100% schema coverage via descriptions. The description adds that these are aliases and gives examples, but does not add substantial new meaning beyond what the schema already provides. Baseline 3 is appropriate as the schema covers everything.

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

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

The description clearly states that the tool answers questions about various real-world data sources (SEC filings, FDA, etc.) and returns structured answers with citations. It identifies the resource (any factual question) and verb (ask/routes). However, it does not differentiate from the sibling 'ask_pipeworx_grounded', which may overlap, so purpose is very clear but not fully distinct.

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 'PREFER OVER WEB SEARCH' and provides a comprehensive list of use cases (SEC filings, FDA data, etc.), specific query phrases ('what is', 'look up', etc.), and examples. It gives strong guidance on when to use this tool over alternatives, including the note to use even when web search could answer.

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, openWorldHint, idempotentHint. The description adds significant behavioral context including the exact refusal reasons (not_in_source, no_tool_match, tool_error, etc.), the extra LLM call cost, and the return format. 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 informative and well-structured, starting with the key purpose. It contains every necessary detail, though slightly verbose. Could be trimmed by a sentence without losing clarity.

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

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

Fully covers the return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and error handling, which compensates for the lack of an output schema. With 6 parameters but only 1 required, the description explains the tool's behavior completely.

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

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

Schema coverage is 100% with multiple aliases (q, text, input, query, prompt, question). The description mentions 'fills arguments' but does not add new meaning beyond what the schema already provides about the question parameter.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, explains its routing and extraction process, and distinguishes it from the sibling tool ask_pipeworx by noting the extra LLM call cost and use case.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples (financial verdicts, legal claims, medical lookups). Also advises to prefer ask_pipeworx for casual lookups.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive context: fan-out patterns, response shapes, resolver contract, safety mechanisms (low-confidence short-circuit, closed market handling), and edge cases. 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, with multiple paragraphs and many detailed examples. While comprehensive, it could be more structured (e.g., using bullet points for fan-out examples) and less verbose. Some details like specific fan-out examples add bulk without being essential for basic understanding.

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

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

No output schema exists, so the description bears full burden. It covers response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields, safety mechanisms, and edge cases for closed markets. This is thorough and leaves little ambiguity.

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

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

Schema description coverage is 100% with all 3 parameters described. The description adds value by explaining the market parameter accepts slug, URL, or question text; depth parameter semantics; and include_raw parameter with response size implications. This goes beyond the schema.

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

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

The description explicitly states the verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides clear usage examples and distinguishes from siblings like polymarket_edges by focusing on individual bet research.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides classifiers and fan-out examples. However, it does not explicitly state when NOT to use this tool vs alternatives, and the sibling list includes tools like polymarket_edges that might overlap.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds behavioral details: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, and for drugs pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also notes results are sorted by primary metric and returns citation URIs.

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

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

The description is relatively long but front-loaded with common user queries, making it scannable. Every sentence adds value, though some redundancy could be trimmed. It earns a 4 for being informative without excessive verbosity.

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

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

With 2 parameters, no output schema, and full schema coverage, the description is complete. It explains what data is returned (paired data + citation URIs) and handles edge cases (off-calendar fiscal years). No gaps remain for the 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?

The input schema has 100% coverage, but the description adds significant meaning: it explains the 'type' enum values ('company' pulls financials, 'drug' pulls adverse events), and for 'values' it gives specific examples and constraints (2-5 tickers/CIKs or drug names). This surpasses 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 common user queries and clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups and specifies the data pulled for each type, making the purpose immediately clear.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive. It also gives examples of when to use (phrases like 'compare X and Y') and lists entity types with specific data sources, offering sufficient guidance.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that results include 'names, descriptions, and full input schemas (with curated examples)' and are 'ready to call directly.' This goes beyond annotations by detailing output format and actionable nature.

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 yet informative, front-loading the core purpose, listing domains, and explaining the return structure. Every sentence adds value; no redundancies. Slightly wordy but efficient for the information density.

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

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

No output schema exists, but the description explains that results contain names, descriptions, input schemas with examples. This is sufficient for an agent to understand what to expect. It covers the key aspect of being ready-to-call but omits details like pagination or error handling.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The description reinforces that 'query' accepts natural language but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task.' It uses a specific verb-resource pair and distinguishes itself from sibling tools by being the only tool for discovering tools. No tautology or ambiguity.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set.' It provides context on when to use and lists example domains. It does not explicitly name alternatives or exclusions, but the guidance is clear for a discovery tool.

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

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

Annotations indicate read-only, open-world, and idempotent behavior. The description adds that it fans out across multiple sources, mentions a sunset limitation for patents (soft-fail), and describes fallback behavior for news. This adds useful context beyond annotations, though it could detail error handling more.

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

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

The description is long but every sentence adds value, with effective front-loading via example queries. It could benefit from bullet points for readability, but remains appropriately sized for the complexity.

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

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

Given the complexity and lack of output schema, the description covers return fields, sources, and limitations. It is sufficiently complete for an agent to understand what the tool provides, though a note on return size or pagination would enhance 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?

Schema coverage is 100% with descriptions for both parameters. The description reinforces constraints (e.g., names not supported, ticker or CIK format) and provides examples, adding 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 begins with numerous example queries, clearly states it produces 'full cross-source profile of a US public company in ONE parallel call,' and distinguishes itself from chaining individual lookups. It explicitly lists what the tool returns, making its purpose unmistakable.

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

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

The description advises to prefer this tool over chaining when a holistic view is needed, and explicitly states that names are not supported, directing users to 'resolve_entity' first. This 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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing with related tools, which is sufficient for a simple delete operation. No contradictions with annotations.

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

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

The description is concise with three sentences, front-loading the core action. Every sentence adds value, and there is no unnecessary information.

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

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

Given the low complexity of the tool (single required parameter, no output schema, clear annotations), the description covers what the tool does, when to use it, and its relationship to siblings, making it contextually 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% for the single parameter 'key', which is already described as 'Memory key to delete'. The description adds no additional meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the action ('Delete a previously stored memory by key'), specifies the resource ('memory'), and mentions pairing with sibling tools 'remember' and 'recall', which distinguishes it from other tools.

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

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

It provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. While it doesn't explicitly state when not to use it, the positive guidance is strong enough for an agent to make appropriate decisions.

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 no behavioral context beyond what annotations already provide. Annotations indicate read-only, idempotent, and non-destructive behavior, which the description does not contradict or enhance. No additional traits like permissions or side effects are disclosed.

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?

While extremely short, the description is under-specified to the point of being unhelpful. Conciseness should not come at the expense of clarity.

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

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

Given the tool has a single required parameter and an output schema (not shown), the description is insufficient. It does not explain what detail is returned or how the tool fits among siblings. The description is woefully incomplete for an agent to reliably use this 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 0%, and the description only parenthetically mentions 'universe' without explaining that 'universe_id' expects a numeric identifier or what it represents. The description fails to add meaning to the parameter.

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

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

The description 'Game (universe) detail.' is vague. It does not clearly state what the tool does beyond hinting at providing details about a game related to a universe. It does not specify the action (e.g., retrieve, show) or the resource (e.g., game object).

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?

No guidance is provided on when to use this tool versus alternatives like 'entity_profile' or 'compare_entities'. The description lacks any context about appropriate use cases or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context by detailing the process (fetches page, extracts title/description/key links, emits markdown) and the output format ('single text blob ready to drop at site-root/llms.txt'). This goes beyond annotations and discloses key behavioral traits.

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 paragraph of three sentences. The first sentence delivers the core purpose and target audience, the second explains the process and output, and the third lists use cases. Every sentence earns its place without redundancy or filler.

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

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

Given the tool has only two parameters, no output schema, and full schema coverage, the description provides all necessary context: what it does, how it works, output format, and when to use it. It is complete for an agent to understand and invoke the tool correctly.

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

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

The input schema achieves 100% description coverage, so the schema already documents both parameters (url and max_links). The description does not add additional semantic meaning beyond what the schema provides; it merely restates the url parameter implicitly. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (for AI crawlers to index cleanly). It also lists target users (ChatGPT, Claude, Perplexity) and provides a use case triplet, making the purpose specific and distinct from siblings.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitors), which helps the agent decide when to use it. However, it does not explicitly state when not to use it or compare with alternatives, though the sibling set suggests no direct competitor.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which convey safety and idempotency. However, the description adds no behavioral context beyond these structured fields (e.g., whether it fetches from cache, returns paginated results, or requires authentication).

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?

While extremely concise (2 words), the description sacrifices necessary detail. Conciseness should not come at the expense of clarity; here it results in an under-specified tool definition.

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?

Though an output schema exists, the description does not hint at the structure or content of the returned data (e.g., group name, member list, permissions). For a tool with one parameter, the description is incomplete and leaves the agent guessing.

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 1 parameter (group_id) with 0% description coverage. The description 'Group detail.' does not explain what the parameter represents or how to specify it (e.g., format, expected range). Given low schema coverage, the description should compensate but fails to do so.

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 'Group detail.' is vague and lacks a verb. It does not specify what kind of detail is retrieved (e.g., members, settings). It is only slightly more informative than the name, making it nearly a tautology.

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?

No guidance is provided on when to use this tool versus sibling tools like 'entity_profile', 'user', or 'user_by_username'. There is no mention of prerequisites or context for invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return fields (id, type, params, created_at, last_fired_at, fire_count) and hinting at cancellation use case, which is not implied by annotations alone.

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 with no wasted words. It starts with the action and then lists return fields, followed by usage guidance. Every sentence is essential and well-placed.

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

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

Given no output schema, the description adequately explains the return format. It covers the main purpose and offers context for reviewing subscriptions. However, it lacks mention of potential pagination or limits, but the tool is simple with one optional parameter.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any additional meaning about the parameter beyond what the schema already provides. No extra context for the parameter is given.

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 lists the caller's active subscriptions, specifies the returned fields, and distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reading current subscriptions.

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

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

The description includes explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it does not explicitly state when not to use it, 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?

Description discloses traits beyond annotations: free usage, daily rate limit of 5 per identifier, signal influences roadmap. Annotations only indicate non-readonly, non-idempotent, etc., but description adds valuable behavioral context.

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

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

Extremely concise: three sentences cover purpose, usage, formatting rules, and constraints. Front-loaded with the core purpose, then usage, then behavioral details. 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?

Given no output schema and simple inputs, description is fully complete. It covers all aspects: when, how, what to include, limitations. No gaps remain for an agent to misinterpret.

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

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

Schema coverage is 100%, but description adds meaningful guidance: message should be 1-2 sentences, max 2000 chars; type enum is expanded with definitions; context is optional. This adds value 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 sends feedback to the Pipeworx team, enumerating specific feedback types (bug, feature, data_gap, praise). It distinguishes itself from all sibling tools, none of which serve a feedback purpose.

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

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

Explicitly specifies when to use: for bugs, missing features, data gaps, or praise. Provides clear directives: describe in terms of Pipeworx tools/packs, don't paste end-user prompts. 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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by revealing caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). No contradictions with annotations.

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

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

The description is concise and well-structured: starts with the core function, then lists use cases with bullet points, and ends with technical details. Every sentence is substantive, and the length is appropriate for the tool's simplicity.

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 read-only aggregation tool with one optional parameter and no output schema, the description covers all necessary aspects: what is returned, use cases, caching, data source, and privacy. It fully prepares the agent for proper 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% for the single parameter 'window' with enum. The description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the schema's enum descriptions.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over customizable windows (24h, 7d, 30d). It uses strong verb 'Returns' and specifies the resource (top tools/packs on Pipeworx). It distinguishes itself from siblings by focusing on trending calls from other AI agents, not general 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?

Three explicit use cases are listed: discovering hot data sources, confirming canonical tool, and checking alignment with agent needs. This provides clear context for when to use the tool, and the mention of windows implies when to choose shorter vs longer durations.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: the algorithmic approach (monotonicity violations, partition-check), semantic anchoring with Jaccard similarity, partition filtering for placeholders, and the structure of the response. 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 well-structured with clear headings (SEMANTIC ANCHOR, PARTITION FILTER, Response) and front-loaded with the requirement statement. While thorough, it is somewhat verbose; a slightly more concise version could improve readability without losing value.

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

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

Given that there is no output schema and only two parameters, the description fully covers the tool's behavior, input requirements, response format, and edge cases (low similarity, placeholder filtering). It is complete and leaves no major gaps for an agent to infer.

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

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

Both parameters (event and topic) are fully described in the description with examples and usage guidance, complementing the schema. The description explains accepted formats (slugs, full URLs) and the behavioral differences between the two modes, adding significant meaning beyond the schema's description.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific recommendations, making it easy for an agent to select the correct mode. The resource (Polymarket arbitrage) and methods are explicitly named.

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

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

The description provides explicit usage guidelines: it requires one of event or topic, recommends event for specific markets and topic for cross-event scanning, and explains what cross-event mode catches that single-event misses. However, it does not explicitly state when not to use this tool versus sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description goes far beyond by detailing caching (1h KV-level), model internals (e.g., lognormal barrier, GDELT ratio), edge calculations (net of slippage, Kelly fractions), and diagnostics. It also warns about Fed candidates and market move warnings. 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 contains extensive detail, which is valuable but not concise. It is well-structured with sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). However, verbosity detracts from quick comprehension. A 3 reflects adequate but not optimal 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 complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), edge calculations, knob effects, and caching. It fully compensates for the missing output schema and provides all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description adds overall context (e.g., tradeable-edge knobs) but does not significantly enhance per-parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the intended use case ('what should I bet on today') and the overall value proposition (discovery without paging). This is a specific verb+resource that distinguishes the tool from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 extensive guidance on when to use, including model families, adjustable knobs (min_liquidity, max_spread_pp), and diagnostics for empty segments. However, it does not explicitly compare against sibling tools or state when not to use this tool in favor of alternatives. The context is clear but lacks exclusions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: safety fields (compatibility_warning conditions, temporal alignment, skipped_cross counters) that explain how the tool handles mismatches, beyond what annotations provide. 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 comprehensive but somewhat lengthy. However, it is well-structured with clear sections (overview, modes, response, safety fields) and every sentence adds value. Could tighten slightly but high utility.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spreads, safety fields) and edge cases. For a complex tool with multiple modes and safety checks, it provides complete context 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% and description enriches each parameter: topic lists all 10 values with examples, kalshi_event_ticker and polymarket_event_slug are explained with examples and override behavior. This adds meaning beyond JSON 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifying the verb 'retrieve' (implied) and the resource (spread). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue 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?

The description explicitly outlines two modes ('topic' shortcuts and explicit ticker/slug) and provides guidance on when each is appropriate. It warns that pre-mapped topics often return compatibility warnings, setting realistic expectations and preventing misuse.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining scope (identifier-based) and the interaction with sibling tools. It does not violate annotations.

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

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

Two sentences, front-loaded with core functionality, no wasted words. Every sentence serves a purpose: functionality and usage context.

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

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

For a simple 1-parameter read tool, the description covers purpose, usage, scope, and sibling pairing. No output schema needed; the behavior is clear.

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

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

Schema coverage is 100% with a single optional parameter 'key'. The description adds context about omitting the key to list all keys and provides examples of what keys represent (ticker, address, notes), going beyond the schema's simple description.

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

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

The description clearly states the tool retrieves a saved value via 'remember' or lists all keys. It specifies the verb 'retrieve' and resource 'value' or 'keys', and distinguishes from siblings 'remember' and 'forget'.

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

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

The description provides clear examples of when to use (look up target ticker, address, research notes) and states it avoids re-deriving context. It mentions scope and pairing with 'remember' and 'forget', but does not explicitly exclude other contexts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it explains the mark_read side effect (flags events as read, affecting future calls), the return format, and polling behavior. No contradictions.

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

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

The description is a single paragraph that is relatively concise, covering purpose, key features, and usage notes in three sentences. It front-loads the main action. Minor improvement could be structuring with bullet points or separating return info, but it is still efficient.

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

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

Given no output schema, the description adequately covers return fields, filtering options, mark_read behavior, polling suitability, and an alternative access method. For a straightforward read-only tool, this is comprehensive.

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

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

Schema coverage is 100%, but the description enriches parameter meaning beyond schema: it specifies filter by type with an example ('sec_8k'), explains that since filters with ISO timestamp, and clarifies mark_read's effect on subsequent calls. It also mentions the default limit of 50.

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

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

The description clearly states the tool pulls fired events from a subscription feed and specifies the return fields (source, citation_uri, raw event payload). It distinguishes the tool by detailing its capabilities like filtering and mark_read, making the purpose unambiguous.

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

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

The description provides clear context on when to use the tool (reading alerts from subscription feed) and mentions polling suitability. It does not explicitly exclude scenarios or list alternatives among sibling tools, but it does mention an alternative HTTP endpoint for scripts/dashboards.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description explains the fan-out to multiple sources, fallback from GDELT to GNews, and the soft-fail for USPTO. These behavioral details significantly aid agent understanding.

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 but packs many details without waste. It could benefit from bullet points for readability, but every sentence adds value. It is concise for the amount of 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 no output schema, the description covers return structure (changes[], total_changes, URIs), all parameter behaviors, source details, fallback logic, and an alternative tool. It provides complete context for an agent to use the tool.

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

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

Although schema coverage is 100%, the description adds valuable meaning: explains the since parameter accepts ISO dates or relative shorthands (with examples), value can be ticker or CIK, and type is limited to 'company'. This enhances agent usage.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from the sibling tool entity_profile by advising when to use that alternative.

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

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

The description explicitly advises using entity_profile instead for static profiles, and provides example queries that indicate appropriate use cases. It also notes the fallback behavior and soft-failure of USPTO.

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

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

Adds behavioral context beyond annotations: persistence depends on authentication (persistent vs 24-hour retention), and storage is scoped by identifier. Annotations already indicate non-destructive and idempotent, and description reinforces these.

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?

Concise and well-structured: opens with the core purpose, then specifies when to use, followed by technical details (scoping, persistence), and ends with pairing hints. No unnecessary words.

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

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

Given 2 parameters with 100% schema coverage and no output schema, the description fully addresses how to use the tool, including lifecycle and scope, making it self-contained for correct invocation.

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

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

Schema already has 100% coverage with descriptions; description adds concrete examples for keys (e.g., 'subject_property', 'target_ticker') and clarifies value as any text, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and distinguishes it from siblings like 'recall' and 'forget' by specifying key-value pair storage scoped by identifier.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and references sibling tools for retrieval/deletion. Could explicitly state when not to use, but overall strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that each call cascades through several lookup endpoints internally, and details the citation URIs and data sources for each type. 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?

Starts with illustrative examples, then clear usage advice, then detailed per-type information. Every sentence adds value; no fluff. Well-structured for quick parsing.

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 no output schema and multiple entity types, the description thoroughly explains inputs, outputs, and internal behavior (cascading lookups). Covers citation URIs and specific data sources, making it complete 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 covers both parameters with descriptions. Description reinforces with examples (ticker, CIK, name for company; brand/generic for drug), adding practical usage guidance 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?

Clear verb+resource: resolves names to identifiers. Provides concrete example queries and explicitly distinguishes from sibling tools by stating this is the first step when you have a name but need an ID. Supported types are listed with specific outputs.

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 FIRST whenever you have a name but need an ID.' Gives context for when to call. Does not mention when not to use or alternatives, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating safety and idempotency. The description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 three sentences, front-loaded with the primary purpose, free of filler, and efficiently conveys usage, method, and output. 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?

The tool has moderate complexity (4 params, 1 required, no output schema). The description adequately explains the output format (ranked list with metrics) and how it differs from siblings (compare_entities, ai_visibility_check). There is no output schema, so returning such detail is sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal parameter-specific meaning beyond the schema (e.g., 'first entry treated as subject'). It does not provide new semantic depth for parameters like models or _apiKey beyond what the schema offers.

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 a specific verb-resource pair ('compare AI visibility across multiple entities') and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic). It uses concrete examples ('does Claude know about us') and specifies the output (ranked list with metrics).

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

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

The description explicitly frames the use case ('competitive AI-marketing audits') and clarifies the input expectation ('your brand + N competitors'). However, it does not explicitly state when not to use it or name alternative tools, leaving a slight gap in exclusion guidance.

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

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

The description discloses key behavioral traits beyond annotations: it fans out across two external services (deps.dev and bundlephobia), degrades gracefully on partial failures, and can take 5-30s for bundlephobia's first measurement. This adds significant context on top of the readOnlyHint and idempotentHint annotations, which already indicate the tool is safe and idempotent.

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

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

The description is fairly long but efficiently packed with valuable information. It is front-loaded with the core purpose, then usage guidelines, then details on response fields and limitations. Every sentence contributes meaning, though it could be slightly more concise without losing clarity.

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

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

Given no output schema, the description comprehensively details the return structure (summary block fields, per-advisory details, links, alternative versions). It also addresses edge cases like timeouts and partial failures, making the description complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters already described in the input schema. The description does not add new semantic details about the parameters beyond what is in the schema, so a baseline score of 3 is appropriate. It does, however, provide context on how the parameters are used in the composite check.

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 very clearly states the tool's purpose: a composite check for adding npm packages, covering license, advisories, version history, bundle size, and tree-shake support. It distinguishes itself from sibling tools by its specific focus on npm package evaluation, which no other sibling tool directly addresses.

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

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

The description explicitly states when to use: for questions about safety, popularity, size, or cost of adding an npm package. It also provides a clear alternative for other ecosystems (PyPI, Maven, etc.) and notes potential timeout issues for bundlephobia's first measurement.

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

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

Discloses truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and that returned passages include offsets and similarity scores. This adds significant context beyond the annotations, which already indicate safety traits.

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

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

Five sentences that efficiently cover purpose, usage, behavior, and pairing. No filler; each sentence adds value.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and scores). Covers input constraints, algorithmic details, and integration guidance. Complete for a search tool.

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

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

Schema coverage is 100%, but description adds meaning: clarifies text max length, query examples, limit default (5). Provides practical context beyond schema descriptions.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific verbs like 'search within' and 'pass the text you already pulled'. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the pairing and when to use each.

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

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

Provides explicit guidance on when to use ('when the record is too big to cram into the prompt') and pairs with ask_pipeworx_grounded for grounding. Lacks explicit 'do not use when' scenarios, but the positive guidance is strong.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses account requirements, webhook secret one-time return, and auto-disable after 10 failures. No contradiction with annotations.

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

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

The description is packed with information but well-structured: purpose first, then requirements, types, and delivery channels. Could be slightly more concise, 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?

The description covers required and optional parameters, return value (subscription ID), and edge cases (webhook secret, auto-disable). With no output schema, it adequately explains what to expect.

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

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

Schema covers 100% of parameters. The description adds value with examples (e.g., item codes, topics) and constraints (SMS must match verified phone, webhook HTTPS only). This enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies when to use the tool for live data monitoring and notes prerequisites (Pipeworx OAuth account, phone verification for SMS). It does not explicitly mention when not to use it, but provides clear context and limitations like SMS cap.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description reveals the tool returns live catalog of thousands of tools, category-bucketed examples, and exact tool calls. It matches the read-only, idempotent nature and adds context about the response structure.

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 with front-loaded intent and clear organization. Each sentence serves a purpose, though it could be slightly more concise.

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

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

Given the simple input schema (1 optional param, no output schema) and rich annotations, the description is fully complete: covers purpose, usage, parameter behavior, and expected output structure.

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

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

The only parameter 'topic' is well described: optional, with a list of focus areas (finance, pharma, etc.) and the effect of omitting it (cross-category spread). Schema coverage is 100% and the description adds meaningful usage guidance.

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

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

The description clearly states the tool returns onboarding example questions bucketed by category, with exact tool+argument shapes. It distinguishes itself from siblings by being the 'onboarding entry point' and lists specific use cases like 'getting started' and 'what data do you have?'.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also specifies when to pass the optional 'topic' argument and that omitting it gives a full spread.

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

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

Discloses key behaviors beyond annotations: ownership enforcement, soft deactivation (not deletion), and preservation of historical events via 'recent_alerts'. No contradictions with annotations.

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

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

Two sentences, no fluff. First sentence states action, second adds ownership and behavioral nuance. Highly concise and structured.

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

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

Given one parameter, no output schema, and rich annotations, the description fully covers purpose, parameter origin, ownership, and behavioral impact. References siblings ('subscribe', 'recent_alerts') 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?

Schema covers the single parameter 'id' with description. Description adds value by specifying the id is a UUID from 'subscribe', providing context beyond schema.

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

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

Clearly states action 'Cancel a subscription by id', specifies resource (subscription), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Provides clear context for usage: ownership enforcement ('only cancel your own subscriptions'). Implicitly tells when not to use (cannot cancel others'), though no explicit alternatives listed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond the word 'profile'.

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?

Extremely short but not effective; it is under-specified rather than concise. The single phrase does not earn 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?

Given the tool has one parameter, multiple siblings, and an output schema, the description is far too minimal to guide proper usage or interpretation.

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 0%, but the description provides no explanation of the required parameter 'user_id'. It fails to add any meaning beyond the schema.

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

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

The description 'User profile.' is too vague; it doesn't specify the action (e.g., get, fetch) and fails to distinguish from many sibling user-related tools like user_badges or user_by_username.

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?

No guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which sufficiently convey safety and idempotency. The description adds no behavioral details but does not contradict annotations, so a baseline score of 3 is appropriate.

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

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

The description is extremely short but suffers from under-specification rather than conciseness. It does not earn its place as it provides no actionable information for the agent.

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

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

Despite having an output schema, the description does not indicate what the tool returns (e.g., badge details, counts). The description is too minimal to be complete for a tool with three parameters and many sibling tools.

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

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

Schema description coverage is 0%, and the description fails to explain the meaning or usage of any parameter (limit, user_id, sortOrder). The examples in the schema are not part of the description, so the agent receives no guidance on parameter semantics.

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 'Badges.' is a tautology that restates the tool name without specifying a verb or resource. It does not clarify what the tool does (e.g., list, retrieve, manage badges) or distinguish it from sibling tools like user_games or user_friends.

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?

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, filtering options, or scenarios where user_badges is preferred over other tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's simplicity is acceptable. However, it adds no extra behavioral details (e.g., error handling, idempotency implications). With annotations covering safety, a 3 is appropriate.

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

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

The description is extremely concise, using a single sentence to convey the function. No wasted words, though it may be too terse for complex scenarios. For a simple lookup with one parameter, this level of conciseness is efficient.

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

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

Given the tool's simplicity (one parameter, output schema present), the description minimally covers the task. It does not mention edge cases (e.g., nonexistent username), return type beyond 'user id', or any error conditions. The existence of an output schema partially compensates, but the description could be more self-contained.

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

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

Schema description coverage is 0%, requiring the description to compensate. The description only vaguely mentions 'username' without specifying format, required scoping, or allowed values. The example in the schema ('builderman') mitigates but doesn't fully substitute for explicit parameter documentation.

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 'resolve username to user id' with a specific verb and resource. It is distinct from sibling tools like 'user', 'user_badges', and 'resolve_entity' by precisely indicating a username-to-ID mapping.

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?

No guidance on when to use this tool versus siblings such as 'user' or 'resolve_entity'. The description does not mention prerequisites, alternatives, or exclusion criteria, leaving the agent to infer 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 adds no behavioral information beyond the annotations. While annotations indicate readOnly, idempotent, and non-destructive behavior, the description fails to explain any additional traits such as authentication needs, rate limits, or response format.

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 overly concise to the point of being under-specified. While short, it sacrifices clarity and usefulness. It does not effectively communicate the tool's purpose or usage.

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 presence of an output schema, the description need not explain return values, but it still lacks completeness regarding parameter meaning and usage context. The tool is simple, but the description could easily be more 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 0%, and the description does not explain the user_id parameter. The example in the schema provides minimal context, but the description itself offers no semantic value for parameters.

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

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

The description 'Follower count' vaguely indicates the tool returns a count of followers, but it does not explicitly state that it retrieves the follower count for a user identified by the user_id parameter. The title and name help, but the description alone lacks clarity on the resource being accessed.

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?

No guidance is provided on when to use this tool versus sibling tools like user_followings_count or user_friends. The description does not specify any prerequisites or context for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds no further behavioral context, but for a simple count, this is acceptable.

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

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

The description is extremely concise at two words, but it sacrifices necessary detail. It is not wasteful, but it could be expanded to add clarity without becoming verbose.

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 and presence of an output schema, the description is minimally adequate. However, it lacks completeness by not explaining what 'following count' means or how the result is structured.

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 0%, so the description must compensate. The single parameter 'user_id' is not described in the text; the description only says 'Following count,' which implies the parameter is the user, but does not clarify its role or format.

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 title 'User Followings Count' and description 'Following count.' clearly indicate the tool retrieves the count of followings for a user. It distinguishes from sibling 'user_followers_count' by the direction of the relationship.

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention context, prerequisites, or when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds no additional behavioral context (e.g., what the returned list contains, whether pagination is supported, or if user must exist). It fails to add 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 extremely short (two words) but at the cost of essential information. It is not appropriately sized for a tool with one parameter and multiple siblings; it lacks necessary detail, making it under-specified rather than concise.

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

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

Given the presence of an output schema, the description does not need to explain return values, but it fails to define the tool's scope (e.g., lists friends of the specified user, returns user IDs or objects). The description is incomplete for a simple 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 0%, and the description does not explain the user_id parameter. The parameter's purpose is only inferable from the tool name, but no explicit semantics (e.g., 'the user whose friends to retrieve') are provided.

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 'Friends list.' is essentially a tautology of the tool name and title. It implies a read operation for a list of friends but provides no verb or resource context to differentiate from sibling tools like user_followers_count or user_followings_count.

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?

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives, nor does it specify any prerequisites or exclusions. With multiple similar sibling tools, this omission is critical.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds no additional behavioral context such as pagination, ordering, or the fact that it requires a user_id.

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?

While very short, the description is under-specified. It does not earn its place because it provides no useful information beyond the tool name.

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

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

Despite having an output schema and rich annotations, the description is too minimal to support an agent in correctly selecting or invoking this tool. It lacks completeness for a tool with 3 parameters and 1 required field.

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 0%, and the description provides no explanation of any parameter. The meaning and acceptable values for 'limit', 'user_id', and 'sortOrder' are left entirely to the schema, which lacks descriptions.

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

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

Description is 'Created games.' which essentially restates the name. It does not use a specific verb to indicate the action (e.g., list, retrieve, fetch) nor does it clarify the scope (e.g., games for a user). It fails to distinguish from sibling 'game' 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?

No guidance on when to use this tool versus alternatives like 'game' or other user tools. There is no context about prerequisites or typical use cases.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds a meaningful constraint (max 100 ids) beyond annotations, but does not clarify what 'presence' means or any other behavioral 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?

Extremely concise (one sentence) but front-loads the action and key constraint. However, it is too brief for a tool with no parameter descriptions, leaving ambiguity.

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 tool and existing output schema, the description does not explain what presence entails or provide sufficient context for the single parameter. Incomplete for an agent to use confidently.

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 0%, so the description must compensate. It only hints that the parameter 'user_ids' is involved ('for up to 100 user ids'), but does not explain the format or any constraints. Minimal value added.

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 states the action ('Presence') and resource ('user ids'), with a constraint ('up to 100'). It distinguishes from sibling tools like user_badges or user_by_username, but could be more specific (e.g., 'Check if users are online/offline').

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?

No guidance on when to use this tool versus alternatives like user or user_by_username. Does not mention when not to use it or provide any 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?

Discloses return details (verdict, structured form, actual value with citation, percent delta) and states it replaces 4-6 sequential calls. Annotations already declare safe, idempotent, read-only behavior; description adds domain limitation and output format without contradiction.

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

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

Description is thorough but not overly long; each sentence adds value. Front-loaded with examples and usage context. Could be slightly more concise, but overall efficient.

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

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

Covers all necessary aspects: purpose, usage, domain, output format, and replacement benefit. No output schema exists, but description explains return types sufficiently. Annotations complete the safety profile.

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

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

Only one parameter 'claim' with schema description. Description does not add further meaning beyond what schema already provides, and schema coverage is 100%. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool is for fact-checking natural-language claims, specifically company-financial ones, using verbs like 'validate' and examples. It distinguishes itself by noting it replaces multiple sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the domain. Does not mention when not to use or provide alternatives, but such guidance is implicit given sibling tools.

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