Figma

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 additional details about probing LLMs, scoring mechanics, and the free default model vs. BYO Anthropic key add useful behavioral context without contradicting 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 only two sentences, with the first sentence clearly stating the core function and the second providing essential operational details. No extraneous text, and it is front-loaded with the main purpose.

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

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

Given no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response plus combined view). All parameters are documented, use cases are listed, and the tool's complexity (4 parameters, no enums) is fully addressed.

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

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

Schema coverage is 100% with each parameter described. The description adds value by explaining the default model for 'models', the purpose of '_apiKey' for Anthropic, and the optional disambiguation role of 'context'. This enriches the schema information.

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

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

The description explicitly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It specifies the default model and optional Anthropic integration, and lists use cases like AI-marketing audits and competitive monitoring. This clearly distinguishes it from siblings such as 'scan_competitor_ai_presence'.

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 usage contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and implies when to use it. However, it does not explicitly state when not to use it or compare to similar siblings, which would enhance guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds that it returns structured answers with stable citation URIs and routes to the correct tool, which adds value beyond annotations.

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

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

Well-organized with key info front-loaded. Slightly long but effective, with examples and sibling distinctions. 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?

Comprehensive for a tool with no output schema: explains return format (structured answer with citations) and input usage. Covers topic scope, query types, and fallback hierarchy.

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

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

Schema coverage is 100% with all parameters described. Description provides usage examples and context on how to phrase questions, adding meaning beyond the schema definition.

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

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

Clearly states it routes questions to thousands of sources for authoritative structured data with citations. Distinguishes from siblings by mentioning ask_pipeworx_grounded and deep_research as alternatives for specific use cases.

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

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

Explicitly says to prefer over web search for factual questions, provides examples, and specifies when to use other tools (grounded, deep_research, news feeds). Includes 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?

Adds significant context beyond annotations: describes extraction from tool result only, lists explicit refusal reasons and output fields, and notes extra LLM call cost.

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?

Compact but packs all key info; could be slightly better structured with bullet points, but still clear and front-loaded.

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

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

Covers purpose, usage, behavior, output format, failure modes, and cost trade-off. Complex tool well explained without output schema.

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

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

Schema coverage is 100%, so baseline of 3. Description mentions 'question' field and aliases but adds minimal new 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?

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, distinguishes from ask_pipeworx by noting the extra LLM call 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 specifies when to use (quotes, citations, high-stakes domains) and when to prefer sibling (casual lookups), citing cost difference.

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 set readOnlyHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: fan-out to data sources, short-circuit on low confidence, handling of closed/dead markets, wide spread warnings, resolution rule risks, and detailed error handling (GDELT 429s, fallback fields). 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 comprehensive but very long (multiple paragraphs). It is front-loaded with purpose but includes many detailed sub-sections (resolver contract, parent event extractor, news fields). Could be more concise.

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

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

Given the tool's complexity (multiple classifiers, data sources, response shapes), the description covers all aspects: input options, response structure, edge cases (low confidence, closed markets, wide spreads), resolution rules, and error handling. No output schema exists, so the description compensates fully.

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

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

Schema coverage is 100%, and description adds significant value: explains depth enum (quick vs thorough), market input types, include_raw default and use case (when to get full payloads). Also includes examples and 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?

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call, with specific examples of inputs (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes from sibling tools by its focused scope.

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

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

Explicitly states use cases ('should I bet on X', etc.) and provides context for when results may be limited (low-confidence matches, closed markets). However, it does not explicitly compare it to sibling tools or state when not to use it.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds important behavioral details: handling off-calendar fiscal years, sorting by primary metric, and returning citation URIs. This goes beyond annotations without contradiction.

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

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

The description is dense but not overly verbose. It front-loads examples and key guidance. Slightly long but each sentence earns its place, with minimal redundancy.

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

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

Given the tool's complexity (two entity types, multiple metrics), the description covers data sources, return format hints, and sorting. Lacks explicit output schema details, but the information provided is substantial for an agent.

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

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

Schema coverage is 100%. The description enhances understanding by explaining data pulled for each type, giving value examples, and noting max/min items. It adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It specifies the data sources for each type and provides example queries. It distinguishes itself from siblings by noting it replaces multiple sequential lookups.

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

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

The description explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities. It gives specific query examples, but does not fully cover when not to use it, though the context implies alternatives like entity_profile for single entities.

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

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

Discloses many behavioral traits beyond annotations: not open-web search, uses 4,476 tools in parallel, returns verbatim evidence with confidence/source/citation, explicit gaps for unanswered facets, expected 15-60s. Annotations already set readOnlyHint, openWorldHint, idempotentHint, destructiveHint false; description adds context without contradiction.

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

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

The description is detailed but every sentence adds value. It is front-loaded with account requirements. Slightly long but well-structured and informative.

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

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

Given the complexity, no output schema, and annotations present, the description is highly complete. Covers parameters, behavior, use cases, limitations, alternatives, and expected output without relying on output schema.

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

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

Schema covers both parameters 100%. Description adds meaning: explains depth values in terms of facet count and plan requirement, clarifies that question can be broad/multi-part. Provides actionable guidance beyond enum values.

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

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

The description clearly states the tool's purpose: grounded multi-source research across structured data sources, decomposing questions into facets and routing to many tools. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

Provides explicit when-to-use (broad/multi-part questions over structured data) and when-not (breaking/current-news, single lookup). Also names alternatives like ask_pipeworx and explains trade-offs.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context: returns top-N relevant tools with full input schemas (ready to call directly), and explains the output format. No contradictions.

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

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

The description is a single paragraph, front-loaded with the core purpose. It lists many domains, which is valuable but slightly lengthy. Every sentence serves a purpose.

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

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

Given a simple discovery tool with no output schema, the description explains the output (top-N relevant tools with names, descriptions, full schemas). It covers all needed context for an agent to use it 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%. The description explains the 'query' parameter as a natural language description and lists aliases (task, q, search, description), with examples. This adds meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and indicates it returns top-N relevant tools with full schemas. This distinguishes it from sibling tools that are specific data tools.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use and implies alternatives (other tools for specific data).

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, and open-world. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields (recent filings with URIs, fundamentals, patents with fallback, news with fallback, LEI), and notes API sunsets and soft-fails. No contradiction with annotations.

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

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

The description is a single block of text with many example queries, making it somewhat verbose. While front-loaded with the core use case, it could be more structured (e.g., bullet points for return fields). Still, it contains only one sentence of true filler (the example queries) and the rest is substantive.

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

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

Given the tool's complexity (multiple data sources, fallbacks, return fields), the description covers all essential aspects: what it does, what it returns, limitations (names not supported, patent sunset), and references to related tools. Without an output schema, the description adequately explains return values.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: for 'type' it states only 'company' is supported with future plans; for 'value' it clarifies that ticker or zero-padded CIK are accepted and names are not supported, directing to resolve_entity. This provides helpful context.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' lists specific data sources and return fields, and distinguishes itself from sibling tools like resolve_entity by noting that it does not accept names. It also implicitly differentiates from chained single-pack lookups.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'names not supported (use resolve_entity first if you only have a name).' It also mentions the patent API sunset as a soft-fail scenario.

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

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

Annotations already indicate destructive behavior; description reinforces 'delete' and adds context about sensitive data, but doesn't detail side effects or authorization requirements beyond that.

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 brief sentences front-load key information with no wasted words.

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

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

For a simple tool with one parameter and appropriate annotations, the description fully covers purpose, usage, and behavioral context.

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

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

Schema has 100% coverage with a description for the 'key' parameter; description adds no extra semantic information beyond what the schema provides.

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

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

Description clearly states the verb 'delete' and resource 'memory by key', distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

Explicitly lists three use cases (stale context, task completion, clearing sensitive data) and names complementary tools (remember, recall).

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

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

Description aligns with annotations (readOnlyHint, idempotentHint) and adds process details (fetches page, extracts title/description/links). But it does not disclose potential issues like invalid URL handling, rate limits, or caching behavior, missing some transparency.

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

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

Description is a single paragraph with a clear first sentence stating the main action, then a concise list of use cases. Every sentence adds value, though the use-case list could be more streamlined.

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

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

With only 2 parameters and no output schema, description covers the tool's purpose, output format ('single text blob'), and use cases. Annotations cover safety and idempotency. Mostly complete, though could mention error scenarios.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats parameter descriptions from schema (e.g., default and max for max_links) without adding new meaning. No additional semantics beyond schema.

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

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

Description clearly states the tool generates an llms.txt file for any URL, with specific verb 'generate' and resource 'llms.txt file'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by noting use cases: getting a client's site indexed, drafting for own project, auditing competitors.

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

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

Description explicitly lists use cases ('Useful for:...'), providing context for when to use. However, it does not explicitly state when not to use or mention alternative tools, which would strengthen guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering safety and idempotency. The description adds behavioral context by explaining it returns a compact summary without side effects, but does not disclose potential limitations like rate limits or auth requirements. This is acceptable given the annotation coverage.

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

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

The description is two sentences, front-loaded with the core purpose and immediately lists the return fields, followed by a usage tip. Every sentence adds value, and there is no unnecessary detail.

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 (2 parameters, no output schema, comprehensive annotations), the description is fully adequate. It explains the tool's behavior, return value composition, and ideal use case, leaving no gaps for the agent.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description only mentions 'file key' and does not add new semantic information beyond what is in the schema. Therefore, it meets 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 specifies the verb 'Get' and the resource 'compact summary of a Figma design file by its file key'. It lists the returned fields (name, last modified, etc.) and distinguishes from sibling tools like get_file_nodes and get_file_images by emphasizing it does not fetch the full node tree.

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 explicit statement 'Use to understand the structure of a Figma design file without fetching the full node tree' provides clear guidance on when to use this tool, implicitly contrasting with alternatives that retrieve more detailed data.

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 adds the return format (map of node ID to URL) and format options, but annotations already cover safety (readOnly, idempotent). No contradictions.

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

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

Two sentences, no fluff. First sentence defines purpose, second provides use case. Extremely 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?

Adequate for a simple tool with 4 parameters and no output schema. The description mentions the return structure, which compensates for missing output schema.

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

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

Schema has 100% coverage, so baseline is 3. Description does not add significant extra meaning beyond the schema descriptions.

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

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

Description clearly states the tool renders images of specific nodes in a Figma file and returns a map of node IDs to URLs. It is specific in verb and resource, and distinct from siblings like get_file or get_file_nodes.

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

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

Provides a clear use case: 'Use to get visual previews...' It does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns a 'compact map' and the structure of each node, which provides additional behavioral context beyond annotations. No contradictions.

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

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

The description is two sentences, front-loading the action and output. Every sentence adds value with no superfluous words. Highly concise and well-structured.

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

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

Given the simple tool (2 parameters, no output schema), the description explains the return format sufficiently. Combined with the comprehensive parameter schema, the description is complete for its complexity level.

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% for both parameters (file_key and node_ids). The description does not add further parameter-level details beyond what the schema already provides. Baseline 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?

The description clearly states what the tool does: 'Get specific nodes from a Figma design file by their node ids.' It specifies the output format ('compact map of node id to { name, type }') and distinguishes from sibling tools like get_file (full file) and get_file_images (images).

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

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

The description provides explicit usage guidance: 'Use to inspect particular frames, components, or layers within a design file.' This clarifies the intended use case without excluding alternatives explicitly, but context with siblings implies when to use 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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by specifying the data returned (id, email, handle, avatar URL). There is 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 extremely concise: two sentences. The first sentence states the action and output, the second provides the purpose. Every word earns its place; no fluff.

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

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

For a tool with no parameters and a simple read operation, the description covers the essential goal and output fields. It does not specify the exact JSON structure or potential error states, but with annotations indicating idempotency and read-only, this is acceptable.

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

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

The input schema has zero parameters, and schema description coverage is 100% (trivially). The description does not need to add parameter details. Baseline for 0 parameters is 4.

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

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

The description explicitly states the verb 'get', the resource 'signed-in Figma user', and lists the fields returned (id, email, handle, avatar image URL). It clearly distinguishes from siblings; none of the sibling tools appear to retrieve the current user.

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

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

The description provides a direct use case: 'Use to identify whose Figma account is connected.' This is clear context for when to use the tool. However, it does not mention when not to use it or any alternatives, but given the tool's simplicity and zero parameters, this is adequate.

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 value beyond annotations by detailing the specific data returned (id, message, etc.) and the purpose. Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints; the description expands on what the tool does behaviorally.

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 with two sentences, no redundant information, and the key information is front-loaded: what it does, what it returns, and when to use it.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the tool's purpose, output, and usage context. There is no missing information needed for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema description already explains the file_key parameter. The tool description does not add further details about the parameter, so the 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?

The description clearly states the tool lists comments on a Figma design file and specifies the returned fields (id, message, author handle, created time, resolved time), distinguishing it from siblings which are unrelated.

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 it ('to review feedback and discussion on a design'), providing clear context. No explicit exclusions or alternatives are needed due to the tool's specific nature.

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 value by specifying exact return fields, providing clarity beyond annotations.

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

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

Two efficient sentences with no wasted words. Front-loaded with purpose, then usage guidance.

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?

Complete for a simple list tool: covers purpose, return fields, usage, and single parameter. No output schema needed; fields are listed inline.

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 (include_inactive) with clear schema description. No additional meaning added beyond the schema, meeting baseline for 100% coverage.

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

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

Explicitly states 'List the caller's active subscriptions' and enumerates return fields. Clearly distinguishes from subscribe/unsubscribe 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?

Provides concrete usage guidance: 'review what you're monitoring before adding more or to find an id to cancel.' Could mention when not to use (e.g., for detailed filter queries) but covers primary 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 are all false, so description carries full burden. It discloses rate limits (5/identifier/day), that it's free and doesn't count against quota. No contradictions. Provides clear behavioral expectations for the agent.

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 yet comprehensive. Six sentences covering purpose, usage, constraints, and formatting. Front-loaded with action verb. No redundant or vague statements. Every sentence adds value.

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

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

Given the tool's simplicity (feedback submission), no output schema, and full schema coverage, the description is complete. It covers what the tool does, when to use, how to format, limitations, and cost. Agent has all necessary information to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The tool description adds extra context beyond schema: e.g., 'be specific (which tool, what error, what data was missing)' and '1-2 sentences typical, 2000 chars max' for message, and clarifies the use of the type enum.

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 ('tell the Pipeworx team something is broken, missing, or needs to exist') and the resource (the team). It distinguishes itself from sibling tools which are data/research oriented, making the purpose unambiguous.

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

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

Explicitly defines when to use for bugs, feature requests, data gaps, or praise. Includes what not to do (don't paste end-user prompt) and mentions rate limits (5/day), free usage, and no quota impact. Strong guidance on alternatives and context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and output shape (pack, tool, count). 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?

Description is concise (4 sentences) and front-loaded with the key function and return value. Each sentence adds value: purpose, use cases, data nature, caching. No fluff or repetition.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It describes the output content and structure (top packs, tools, call volume), windows, caching, and privacy. The agent has enough information to decide and 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% for the single optional parameter 'window' with enum and description. Description adds extra semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps agents choose effectively. This goes beyond the schema's basic 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?

Description clearly states it returns top tools, top packs, and total call volume over a window. The verb 'returns' and resource 'trending data' are specific. This differentiates from siblings like 'ask_pipeworx' (queries) and 'discover_tools' (tool discovery).

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

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

Description provides three explicit use cases: discovering hot data sources, confirming popular tools, and aligning use cases. It does not explicitly state when not to use it or name alternatives, but the context is clear. The window parameter guidance ('shorter windows surface what's hot right now; longer windows show steady-state demand') adds practical advice.

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 provides extensive behavioral context beyond annotations: it walks child markets, checks ordering, computes partition checks, uses Jaccard similarity, filters placeholders, and performs fill checks against live CLOB depth. Annotations already indicate read-only, open-world, idempotent, and non-destructive traits, and the description aligns with these without contradiction.

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

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

The description is verbose but well-structured with uppercase section headers (REQUIRES, SEMANTIC ANCHOR, etc.) and front-loaded with the requirement. Every sentence is informative, though some redundancy could be trimmed given the complexity.

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

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

The description thoroughly addresses the tool's complexity, covering both modes, edge cases (placeholder slugs, low similarity), response structure including fields, and fill-check behavior. Despite lacking an output schema, the description provides sufficient detail for an agent to understand inputs, outputs, and limitations.

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

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

Both parameters (`event` and `topic`) are fully described in the schema (100% coverage). The description adds substantial value by giving examples of valid slugs, explaining when to use each mode, and detailing the behavioral implications of each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event (single-event) and topic (cross-event) modes, making the purpose specific and differentiated from sibling tools.

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

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

Explicitly states that one of `event` or `topic` is required and no-arg calls fail. Recommends `event` for specific markets and `topic` for cross-event scanning. Also advises not to trade when realizable edge <= 0 and suggests `polymarket_fill_risk` for custom sizing.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive context: caching (1h KV), model details, response structure (by_segment, diagnostics), edge calculation, Kelly sizing, slippage handling, and tradeable-edge filters. It explains why segments may be empty and notes limitations (Fed bets unreliable). 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 long but well-structured with bullet-like formatting (using parentheses and dashes). It front-loads the core purpose. While not extremely concise, the length is justified given the tool's complexity (multiple model families, many parameters). A shorter version could omit some detail, but the structure aids readability.

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

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

Given 9 parameters and no output schema, the description is highly complete. It covers the response structure (by_segment, diagnostics), caching, limitations (Fed bets), and parameter interactions. An agent can fully understand the tool's capabilities and behavior without needing additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond parameter descriptions: it explains usage context, defaults, caveats (e.g., for slippage_pp it notes Polymarket fees and suggests adjustments; for min_partition_leg_kelly it explains why min_kelly doesn't apply to partitions). This enhances understanding and correct invocation.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and clearly distinguishes itself from sibling tools like polymarket_arbitrage by detailing its unique model families and edge detection approach.

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 is built for 'what should I bet on today' and explains when to use parameters (e.g., bump slippage for thin partitions, use min_liquidity to drop thin-book opportunities). However, it does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage, though it does note that Fed bets are excluded from ranking due to unreliable signal.

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 valuable behavioral details: daily snapshots with a 60-day TTL, decay computed from daily closes (not intraday), and the structure of response fields (tracked, expired, snapshot_dates). 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 information-dense and front-loaded with the core purpose. However, it is relatively long and could be slightly more concise by trimming redundant phrasing. Overall well-structured with clear sections.

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

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

Despite lacking an output schema, the description provides a thorough explanation of the response (tracked, expired, snapshot_dates) and covers limitations (TTL, not intraday). Given the tool's complexity and the richness of the description, it is complete enough for an AI agent to understand behavior and output.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond the schema: default and max/min values for days, default and allowed window families, and explains that window refers to snapshot families. It also details the response structure, 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 that the tool provides edge persistence and decay telemetry, answering how long an edge has existed and whether it is shrinking. It contrasts a fresh wide edge with a 3-week-old one, making the purpose highly 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 implicitly guides usage by focusing on historical edge evolution, but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. The context of sibling tools provides some differentiation, but explicit guidance would improve clarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating safe, repeatable, non-destructive behavior. The description adds significant behavioral context beyond annotations: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and for basket mode includes theoretical vs realizable sums, capture_ratio, profit_usd, thin_legs, and forced_directional_risk warnings. 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 lengthy but well-structured: front-loaded with required parameter note, followed by mode-specific behavior, return fields, and usage context. Bold and uppercase highlight key points. Every sentence adds value, though minor trimming could improve conciseness without losing information.

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

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

Given the tool's complexity (two modes, no output schema), the description is remarkably complete. It lists all key return fields for both modes, explains parameter behavior, and warns about partial fills and directional risk. The absence of an output schema is compensated by thorough description, and the annotations cover safety and idempotency.

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

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

Schema description coverage is 100%, but the description adds value by clarifying defaults (side defaults, size_usd default 1000, clamp range) and interpreting size_usd differently for single-market vs basket mode. This goes beyond the schema's basic 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 defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it (before acting on their signals/trades). It also explains two distinct modes (single-market and basket), providing a clear verb+resource+scope.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of not using it (theoretical overround not capturable, partial fills convert arb to directional position) and highlights required parameters ('REQUIRES one of market or event'). This is comprehensive and actionable.

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

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

Annotations already mark it as readonly, idempotent, and non-destructive. The description adds substantial behavioral context: the two modes, compatibility warning conditions (matched_pairs:0 cases), temporal alignment, skipped cross types, and caution that pre-mapped does not equal tradeable. No contradictions.

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

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

The description is well-structured with clear sections (purpose, modes, response, safety fields, temporal alignment, caution). Every sentence adds value; no fluff. It is 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?

For a tool with 3 parameters, no output schema, and complex behavior, the description is exceptionally thorough. It explains the response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and warns about real-world limitations. The agent has all necessary context to use it correctly.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains the topic shortcuts, defines the explicit mode, and clarifies that explicit parameters override topic. It also contextualizes how parameters interact (e.g., topic plus overrides).

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' (single venue) and 'compare_entities' (generic) by focusing specifically on this cross-venue delta.

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

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

Explicitly describes when to use (two modes: topic shortcuts or explicit event identifiers) and provides context about compatibility warnings and that pre-mapped topics may not always yield tradeable spreads. Lacks explicit 'when not to use' but gives enough guidance to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds the dual behavior (single key vs list all) and scoping, providing context beyond annotations.

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

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

Two sentences, no fluff, front-loaded with action then use cases. 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?

For a simple tool with one optional parameter, the description fully explains how to use it (including listing all keys) and its context within the memory system.

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 schema description already explains key omission behavior. The description reinforces this and integrates with the memory system, adding slight extra value.

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

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

The description clearly states the tool retrieves a value by key or lists all keys if omitted, and distinguishes from siblings 'remember' and 'forget' via explicit pairing advice.

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 use cases (look up stored context) and scoping (by identifier), and suggests when to use alongside 'remember' and 'forget'.

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

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

Annotations indicate readOnly and idempotent. The description adds behavioral details: the mark_read parameter flags events as read, affecting future calls. It also describes the returned fields (source, citation_uri, payload). 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 five sentences, front-loaded with the purpose, and each sentence adds necessary detail without fluff. It is efficient and well-structured.

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

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

For a tool with 5 parameters and no output schema, the description covers all key aspects: purpose, parameters, effect (mark_read), returned fields, and usage scenario. It 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% with descriptions. The description adds value by providing an example for 'type' ('sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the effect of 'mark_read' on future calls.

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

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

The description clearly states the action ('Pull fired events') and the resource ('your subscription feed'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on retrieving events.

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

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

The description explains how to use the tool (filter by type and since, mark_read) and mentions an alternative access method (HTTP endpoint). It doesn't explicitly state when not to use, but usage is clear.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds details: fans out to multiple sources, handles rate limits, mentions PatentsView sunset, and specifies output format (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph but is dense with information, front-loaded with usage examples. Slightly more structure (e.g., bullet points) could improve readability, but it remains concise and efficient.

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

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

Given no output schema, the description describes the return structure (changes[], total_changes, pipeworx:// URIs). It covers the main use case thoroughly for a tool of moderate complexity.

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

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

Schema coverage is 100%, but description adds significant meaning: explains `since` accepts ISO dates or relative shorthand, suggests '30d' for typical monitoring, and clarifies `value` can be ticker or CIK. This provides actionable guidance 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 provides a change feed for a company (SEC filings, news, patents) within a time window. It uses specific examples like 'What's new with X' and distinguishes from the sibling tool 'entity_profile', which is for static profiles.

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

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

Explicit instructions on when to use (for recent activity queries) and when not (use entity_profile for static profile). Also explains fallback behavior between GDELT and GNews, and soft-fail for patents API.

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 idempotent and non-destructive. Description adds scoping by identifier and differing persistence for authenticated vs anonymous users.

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

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

Three efficient sentences, front-loaded with purpose, no wasted words.

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

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

Complete for a simple key-value store tool: purpose, usage, persistence, companion tools. Output schema not needed.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds examples but not new semantics 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 the tool saves data for later reuse, with specific examples (ticker, address, preference). Distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use (discover something worth carrying forward) and mentions pairing with recall/forget. Provides context on scoping and persistence.

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, and idempotentHint, so the description adds value by noting internal behavior: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This goes beyond annotations, though it doesn't mention error handling or rate limits.

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

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

The description is efficient and front-loaded with query examples. Every sentence is informative, with no filler. The two paragraphs cover usage, supported types, and return details without unnecessary wordiness.

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

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

Given no output schema, the description fully explains return values for both entity types (ticker, CIK, company_name, citation for company; RxCUI, ingredient, brand, citation for drug). It also describes the internal cascading, making the tool's behavior transparent and complete for an AI agent.

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

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

Schema coverage is 100%, and the description adds substantial meaning: it explains what values are accepted for each type (e.g., for company: ticker, CIK, or name; for drug: brand/generic), provides example values, and mentions auto-disambiguation for company inputs. This far exceeds the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to a canonical identifier, with specific examples ('What's the ticker for...') and explicit supported types (company, drug). The phrase 'Use FIRST whenever you have a name but need an ID' distinguishes it from sibling tools that rely on IDs.

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

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

The description provides explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives concrete query examples. It does not explicitly list when not to use or name alternative tools, but the context with sibling tools makes the usage clear.

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

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

Adds behavioral details beyond annotations: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description complements 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?

Three sentences, no wasted words. Purpose described first, then usage context, then return format. Well-structured for quick 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?

With 4 parameters, no output schema, and annotations present, the description adequately explains the process and output. The agent can understand 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 coverage is 100%, so description adds limited value. It mentions treating first entity as 'subject' for narrative, which is extra context, but otherwise repeats schema info.

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

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

The description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check, and ranks results. This distinguishes it from the sibling tool ai_visibility_check (single entity) and other comparison tools.

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

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

Provides context for competitive AI-marketing audits with an example question. Does not explicitly exclude single-entity use or mention ai_visibility_check as an alternative, but the purpose implies when to use multiple vs single.

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 beyond annotations: describes composite behavior, graceful degradation, bundlephobia's potential 5-30s delay, and that sources_failed lists timeouts. No contradiction with annotations.

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

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

Packs substantial detail into a paragraph. Every sentence adds value, but it is a bit lengthy; could be slightly tighter.

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

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

Despite no output schema, the description thoroughly explains the return value structure (summary, advisories, links, alternatives) and partial failure behavior, making the tool fully understandable.

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

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

Schema covers both parameters fully. Description adds that scoped packages are accepted and that version defaults to latest, providing extra meaning beyond the schema.

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

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

The description clearly states the tool performs a composite 'should I add this npm package' check, fanning out to deps.dev and bundlephobia. It specifies the return blocks and is distinct from sibling tools.

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

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

Explicitly says when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. Also clarifies NPM-only in v1 and points to deps.dev:version for other ecosystems.

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 technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, character offsets and similarity scores. Annotations already declare readOnlyHint and idempotentHint; description enriches with implementation specifics.

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 purpose, each sentence earns its place. No redundant or vague language. Highly efficient.

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

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

Despite no output schema, description specifies return format (passages with offsets and scores) and truncation behavior. Pairs with sibling tool. Fully covers usage, constraints, and behavior given complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining text as 'already pulled' content, query as natural-language with examples, and limit as top-N passages. Provides context beyond schema labels.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from siblings like ask_pipeworx_grounded. Examples like SEC 10-K body make it concrete.

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

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

Explicitly says use when record is too big for prompt, saves context, and returns relevant passages. Mentions pairing with ask_pipeworx_grounded. Missing explicit when-not-to-use, but context is clear.

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

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

Adds behavioral context beyond annotations: notes that webhook signing secret is returned once, auto-disable after 10 consecutive failing runs, and SMS 10/day cap. No contradiction with idempotentHint=true or other annotations.

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

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

Packed with information but efficiently structured using bullet points and examples. Front-loaded with main purpose. Slightly long 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?

Covers all aspects: purpose, requirements, types, delivery channels, constraints, and return value (subscription id). No output schema but description suffices for a creation 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?

With 100% schema coverage, the description adds detailed examples and constraints for each type and delivery option, significantly enriching the schema. For instance, explains subscription types (sec_8k with item codes) and delivery details like webhook signing.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. Differentiates from siblings by being the creation action, distinct from list_subscriptions and unsubscribe.

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

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

Provides explicit prerequisites (Pipeworx OAuth account) and notes that anonymous/BYO cannot persist. Describes delivery channels and caps. However, does not explicitly state when to use this vs. other tools, though the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: it returns category-bucketed example questions with exact tool+argument shape, drawn from a live catalog. This contextualizes the output without overstepping. 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 slightly verbose but well-structured, with front-loaded intuitive examples. Every sentence adds value, explaining purpose, usage, and output. Could be trimmed slightly 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?

For a tool with no output schema, the description fully explains the return format (category-bucketed examples). It covers all aspects: when to use, what topic does, and how it relates to other tools. Complete for a discovery/onboarding tool.

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

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

Schema coverage is 100% and the parameter is optional. The description explains the effect of the topic parameter by listing valid focus areas and what happens when omitted ('full spread'), adding meaning 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 starts with intuitive example questions like 'What can I ask Pipeworx?' and clearly states it is the onboarding entry point. It distinguishes itself from sibling tools by specifying it returns category-bucketed example questions with exact tool calls, making its purpose highly specific.

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

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

Explicitly tells the agent to 'Use this FIRST when you do not yet know what Pipeworx can do'. It provides clear guidance on when to omit topic vs. pass a specific topic (e.g., 'finance'), and mentions it helps learn how to call meta-tools, offering comprehensive 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 important behavioral details beyond annotations: 'deactivated (not deleted)' and ownership enforcement. Annotations already indicate non-destructive and idempotent, and description is consistent.

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

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

Two concise sentences front-load the action and key constraints, with no wasted words.

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

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

For a simple one-parameter tool without an output schema, the description covers purpose, ownership, and effect. It could reference sibling tools like subscribe for additional context, but it is otherwise complete.

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

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

Schema coverage is 100%, and the description repeats the schema's note that the id is returned by subscribe. It does not add new semantic value beyond the schema.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing good context for when to use it. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it uses SEC EDGAR + XBRL, returns specific verdict types, and mentions the efficiency improvement. 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?

Every sentence in the description adds value, including intents, use-case, domain, return structure, and efficiency claim. It is front-loaded with the most critical information and avoids redundancy.

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

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

Given no output schema, the description adequately explains the return values (verdict, structured form, actual value, citation, delta). It also notes the domain limitation (v1). It could mention error handling or unsupported claim types, but is largely 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?

The input schema has 100% coverage for the single parameter 'claim' with a clear description. The description reinforces the schema with examples, adding value by clarifying the expected format and natural language style.

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: verifying natural-language claims against authoritative sources. It lists example user intents ('Is it true that...', 'fact check') and specifies the domain (company-financial claims). It distinguishes from siblings by highlighting the structured verdict output and efficiency (replaces multiple 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported domain (v1: company-financial claims). While it doesn't state explicit exclusions or alternative tools, 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.