stackexchange

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively: it explains that Pipeworx picks the right tool, fills arguments, and returns results, covering key behavioral traits like automation and data source selection. However, it lacks details on potential limitations, such as rate limits, error handling, or data freshness, which could be useful for an 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?

The description is appropriately sized and front-loaded: the first sentence states the core functionality, followed by explanatory details and examples, with every sentence earning its place by clarifying usage or providing context. It avoids redundancy and is structured for quick comprehension, making it highly efficient.

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

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

Given the tool's complexity (natural language processing and automated tool selection), no annotations, and no output schema, the description is mostly complete: it covers purpose, usage, and behavioral aspects well. However, it lacks information on output format, error cases, or limitations, which would help an agent handle responses better, leaving a minor gap in completeness.

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

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

The schema description coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema by explaining the parameter's purpose ('ask a question in plain English') and providing concrete examples that illustrate valid inputs, enhancing understanding of what constitutes a good 'question'. This compensates for the schema's basic description, though it doesn't detail constraints like length or format.

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

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

The description clearly states the tool's purpose with specific verbs ('ask a question', 'get an answer') and resources ('best available data source'), distinguishing it from siblings like 'search_questions' or 'get_answers' by emphasizing natural language input and automated tool selection. It explicitly contrasts with manual tool browsing and schema learning, making the differentiation clear.

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

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

The description provides explicit guidance on when to use this tool: for asking questions in plain English to get automated answers, and when not to use it (no need to browse tools or learn schemas). It implicitly suggests alternatives like sibling tools for more specific operations, such as 'search_questions' for searching or 'get_answers' for retrieving stored answers, by highlighting its unique natural language approach.

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?

No annotations provided, so description carries burden. It states returns paired data and resource URIs, implying read-only behavior, but does not explicitly declare read-only or mention permissions/rate limits. Adequate but not exhaustive.

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

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

Four concise sentences: purpose, company specifics, drug specifics, output/efficiency. Every sentence adds value with no redundancy. Front-loaded with main action.

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

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

No output schema, but description explains return content (paired data + URIs) and mentions the data fields. Could detail output format more, but sufficient for agent decision-making.

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

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

Schema coverage is 100%, baseline 3. Description adds significant context: for type='company' lists specific financial fields, for type='drug' lists counts. This enriches understanding beyond the enum and array 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 compares 2–5 entities side by side, distinguishes between company and drug types with specific data fields, and highlights efficiency gains. It uniquely contrasts with sibling tools, none of which are direct 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?

The description explicitly says to use for comparing 2–5 entities in one call and mentions it replaces 8–15 sequential calls, implying it's for efficient multi-entity comparison. No explicit when-not-to-use or alternatives, 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns the most relevant tools with names and descriptions, which is useful behavioral context. However, it doesn't mention potential limitations like rate limits, authentication needs, or error handling, leaving gaps for a tool with no 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 front-loaded with key information in two concise sentences. Every sentence earns its place: the first explains the tool's function, and the second provides critical usage guidance. There is no wasted text, making it highly 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?

Given the tool's complexity (a search function with 2 parameters) and no output schema, the description is mostly complete. It explains the purpose, usage context, and behavioral output (returns tools with names/descriptions). However, without annotations or output schema, it could benefit from more details on result format or error cases, but it's sufficient for basic understanding.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (query and limit) thoroughly. The description doesn't add any parameter-specific details beyond what's in the schema, such as examples or usage nuances. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('search', 'returns') and resource ('Pipeworx tool catalog'), distinguishing it from siblings by focusing on tool discovery rather than answers or questions. It explicitly mentions what it does: searching by describing needs and returning relevant tools with names and descriptions.

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

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

The description provides explicit guidance on when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This clearly indicates its role as an initial discovery mechanism and sets context for its application, distinguishing it from alternatives like get_answers or search_questions.

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?

No annotations are provided, so the description carries the full burden. It discloses the tool returns citation URIs and replaces 10-15 sequential calls, but does not mention side effects, authorization needs, rate limits, or data freshness. The behavioral disclosure is adequate but could be richer.

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

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

The description is four sentences, front-loaded with the core purpose. Each sentence adds value, and there is no redundant information. Slightly more structured formatting (e.g., bullet points) could improve readability, but it is efficient.

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

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

Given no output schema, the description explains the nature of returned data (citation URIs, specific data types). It is fairly complete for a profiling tool, though it does not discuss response size or performance characteristics, which would be beneficial.

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 the schema by explaining the interpretation of 'type' (only company supported) and 'value' (ticker or CIK) and by directing users to resolve_entity for names. This adds significant context.

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

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

The description clearly states it provides a full entity profile across multiple packs, enumerates data types (SEC filings, XBRL, patents, news, LEI), and specifies it returns pipeworx:// URIs. It also distinguishes itself from the sibling tool usa_recipient_profile.

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

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

The description explicitly advises to use usa_recipient_profile for federal contracts instead. It implies usage for comprehensive entity lookups without listing other exclusions, providing clear context for appropriate choice.

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?

No annotations are provided, so the description carries the full burden. It states 'Delete' implying a destructive mutation, but lacks details on permissions, reversibility, error handling (e.g., if key doesn't exist), or side effects. This is inadequate for a mutation tool with zero 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 a single, efficient sentence with zero waste. It is front-loaded with the core action and resource, making it easy to parse quickly.

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 destructive tool with no annotations and no output schema, the description is insufficient. It lacks critical context like what 'delete' entails (permanent vs. soft deletion), response format, or error conditions, leaving significant gaps for agent understanding.

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

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

Schema description coverage is 100%, with the schema documenting the 'key' parameter as 'Memory key to delete'. The description adds no additional meaning beyond this, such as key format or examples. Baseline 3 is appropriate since the schema does the heavy lifting.

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 specific action ('Delete') and resource ('a stored memory by key'), distinguishing it from sibling tools like 'recall' (retrieve) and 'remember' (store). It precisely communicates the tool's function without ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., needing an existing memory key), exclusions, or how it differs from other deletion-related tools (none listed in siblings, but context is missing).

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return values (answer body, score, acceptance status), which adds useful context beyond the input schema. However, it lacks details on potential errors (e.g., invalid ID), rate limits, authentication needs, or pagination, which are important for a tool interacting with an external API like StackExchange.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and return values without any unnecessary words. It is front-loaded with the main action and resource, making it easy to understand at a glance.

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 moderate complexity (2 parameters, no output schema, no annotations), the description is partially complete. It covers the basic purpose and return values, but it lacks information on error handling, API behavior, or how it relates to the sibling tool, which could help an agent use it more effectively in 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?

The schema description coverage is 100%, so the input schema already documents both parameters ('site' and 'question_id') with clear descriptions. The description does not add any additional meaning or context about the parameters beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema 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?

The description clearly states the tool's purpose with a specific verb ('Get answers') and resource ('for a specific StackExchange question by ID'), and it distinguishes what it returns (answer body, score, acceptance status). However, it does not explicitly differentiate from the sibling tool 'search_questions', which likely searches for questions rather than retrieving answers for a specific one, so it falls short of a perfect score.

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

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

The description implies usage by specifying it retrieves answers for a specific question ID, suggesting it should be used when you have a known question ID. However, it does not provide explicit guidance on when to use this tool versus the sibling 'search_questions' (e.g., for finding questions vs. getting answers), nor does it mention any prerequisites or exclusions, leaving room for ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It discloses the rate limit (5 messages per identifier per day) and notes it is free. It does not detail what happens after sending (e.g., how feedback is processed), but for a feedback tool, this is reasonable.

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 concise sentences. It efficiently states the purpose, lists use cases, and gives critical instructions and constraints. No unnecessary words.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description adequately covers purpose, usage, and constraints. It could mention what happens after submission (e.g., no response) but 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 description coverage is 100%, providing good baseline. The description adds value beyond schema by explaining the types of feedback, instructing to describe with tool/data context, and mentioning rate limits. It also warns against including user prompts, which is not in 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: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, missing data, praise) and distinguishes itself from sibling tools which serve different functions (e.g., asking questions, comparing entities).

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 context: use for feedback types, and includes specific instructions to 'describe what you tried in terms of Pipeworx tools/data' and 'do not include the end-user's prompt verbatim.' It also mentions a rate limit. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings, though the sibling tools are quite distinct.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool retrieves or lists stored memories, which implies read-only behavior, but it doesn't mention potential limitations like rate limits, authentication needs, or what happens if the key doesn't exist. The description adds some context about session persistence but lacks detailed behavioral traits.

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

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

The description is appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and usage. Every sentence earns its place by providing essential information without redundancy or unnecessary details.

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

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

Given the tool's moderate complexity (retrieval/listing with one optional parameter), no annotations, and no output schema, the description is somewhat complete but has gaps. It explains what the tool does and when to use it, but lacks details on return values, error handling, or behavioral constraints, which are important for a tool interacting with stored data.

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

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

The input schema has 1 parameter with 100% coverage, so the baseline is 3. The description adds value by explaining the semantics: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' This clarifies the optional nature of the key parameter and the dual functionality (retrieve vs. list), going beyond the schema's description.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings by specifying retrieval of context saved earlier in the session or previous sessions, which differentiates it from tools like 'remember' (likely for saving) and 'forget' (likely for deletion).

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

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

The description provides explicit guidance on when to use this tool vs. alternatives: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' It also specifies context: 'Use this to retrieve context you saved earlier in the session or in previous sessions,' which implies when to use it (for saved context) and when not to use it (e.g., for new operations not involving stored memories).

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?

With no annotations, the description carries full burden. It details parallel fan-out to multiple sources, return structure (structured changes + count + URIs), and the supported 'since' formats. No contradictions.

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

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

Description is four sentences, each packed with essential information. It is front-loaded with the purpose, and every sentence adds value without redundancy.

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

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

No output schema, but description explains the return format includes structured changes, count, and URIs. It covers all parameters and main use cases, though could mention pagination if applicable.

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. Description adds examples for 'since' (ISO and relative), explains 'value' accepts ticker or CIK, and notes 'type' only supports 'company' today, providing context beyond the 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 tool finds 'what's new about an entity since a given point in time', specifies entity type 'company' and the data sources (SEC EDGAR, GDELT, USPTO). It distinguishes from siblings like 'entity_profile' by explicitly targeting change-monitoring workflows.

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

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

The description advises using it for 'brief me on what happened with X' or change-monitoring workflows, providing clear context. It does not explicitly mention when not to use it, but the use cases are well-defined.

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

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

With no annotations provided, the description carries the full burden and adds valuable behavioral context beyond basic storage. It discloses persistence traits ('Authenticated users get persistent memory; anonymous sessions last 24 hours'), which are critical for understanding data lifespan and authentication impacts. However, it does not cover potential limits like storage capacity or error conditions.

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 appropriately sized and front-loaded, with two efficient sentences that earn their place. The first sentence states the core action and usage, while the second adds crucial behavioral details without redundancy. Every word contributes to understanding, with zero waste.

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 moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and key behavioral traits (persistence rules), but lacks details on return values or error handling. Without an output schema, explaining expected responses would enhance completeness, though the core functionality is well-described.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (key and value). The description does not add any parameter-specific semantics beyond what the schema provides, such as format constraints or usage examples. Baseline 3 is appropriate when the schema handles all parameter documentation.

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

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

The description clearly states the tool's purpose with specific verbs ('store a key-value pair') and resource ('in your session memory'), distinguishing it from siblings like 'recall' (retrieval) and 'forget' (deletion). It explicitly mentions what gets stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous.

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

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

The description provides clear context on when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but does not explicitly state when not to use it or name alternatives. It implies usage for persistence across calls, which helps differentiate from transient operations, though lacks explicit exclusions or sibling comparisons.

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?

With no annotations, the description carries the full burden. It discloses the return fields (ticker, CIK, company name, URIs) and positions it as a single call. However, it does not mention idempotency, rate limits, or authorization needs, leaving some gaps for a read operation of this nature.

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

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

The description is composed of two concise sentences. The first sentence states the core purpose, and the second provides version info, accepted formats, and return values. Every word adds value, and the structure is front-loaded.

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

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

Given the tool's simplicity (2 parameters, no nested objects, no output schema), the description is complete. It covers purpose, input formats, return fields, and utility (replacing multiple calls). No additional information is needed 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?

The input schema has 100% description coverage, and the description adds meaning by explaining the enum ('company') and providing examples for the value parameter (ticker, CIK, name). This enriches the schema details without duplication.

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

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

The description clearly states the tool's purpose: resolving an entity to canonical IDs across Pipeworx data sources. It specifies the supported type (company) and provides concrete examples (ticker, CIK, name). It distinguishes itself from sibling tools by being a specific resolver, replacing multiple lookup 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 implicitly guides usage by stating it replaces 2-3 lookup calls and listing accepted input formats. While it doesn't explicitly state when not to use or name alternatives, the context of sibling tools (e.g., ask_pipeworx) and the focus on canonical IDs provides clear guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return fields (title, body, score, etc.) which is helpful, but lacks critical behavioral details like rate limits, authentication requirements, error handling, pagination behavior, or whether this is a read-only operation. The description doesn't contradict any annotations since none exist.

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

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

The description is appropriately concise with two sentences that efficiently convey the tool's purpose and return values. It's front-loaded with the core functionality and avoids unnecessary elaboration. Every sentence serves a clear purpose.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description provides adequate basic information about what the tool does and what it returns. However, it lacks sufficient behavioral context for a search tool that interacts with external APIs, particularly regarding rate limits, error conditions, and authentication requirements.

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 schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema, providing only general context about the tool's purpose. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the tool's purpose with specific verbs ('search for questions') and resources ('StackOverflow or any StackExchange site'), and distinguishes it from the sibling tool 'get_answers' by focusing on questions rather than answers. However, it doesn't explicitly contrast with the sibling tool beyond the resource difference.

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

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

The description implies usage context by mentioning StackExchange sites, but provides no explicit guidance on when to use this tool versus alternatives like 'get_answers' or other search methods. There's no mention of prerequisites, limitations, or comparative scenarios.

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

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

No annotations provided, so the description must convey behavioral traits. It lists return fields and mentions site flexibility, but lacks details on rate limits, authentication, error handling, or mutability (though 'look up' implies read-only).

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 action and key return fields. No filler, 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?

For a simple lookup tool with no output schema and empty annotations, the description covers purpose, parameters, and return data. Missing error/edge case info but adequate for common usage.

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

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

Schema coverage is 100% with clear descriptions. The description adds context by specifying default site, usage examples, and how to find user_id, enhancing understanding beyond the schema alone.

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

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

Clearly states the action ('Look up') and resource ('StackExchange user by numeric ID'). Lists return fields, making the tool's purpose unambiguous and distinct from sibling tools like search_questions or get_answers.

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

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

No guidance on when to use this tool vs alternatives or when not to use it. Does not mention prerequisites or exclusions, leaving the agent to infer context from the description alone.

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?

With no annotations, the description carries the full burden. It adequately describes the tool's behavior: it returns a verdict (confirmed, approximately_correct, refuted, inconclusive, unsupported), the extracted structured form, actual value with a citation, and percent delta. It also highlights that it consolidates multiple agent calls. However, it lacks details on error handling or limitations.

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

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

The description is concise with four sentences, each adding value: purpose, domain support, return fields, and benefit. It is front-loaded and efficient with no wasted words.

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

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

Given no output schema, the description covers return values and domain well. It specifies the supported financial metrics (revenue, net income, cash) and data sources. It lacks explicit mention of error cases or limitations, but the scope is clear.

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

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

Although schema coverage is 100%, the description adds significant value by providing concrete examples of claims and explaining the return structure, which goes beyond the schema's parameter description. The examples clarify expected input format.

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

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

The description clearly states the tool's purpose: fact-checking natural-language claims against authoritative sources. It specifies the domain (company-financial claims for public US companies) and differentiates from siblings like ask_pipeworx and compare_entities, which serve different purposes.

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

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

The description provides clear context for when to use the tool: for company-financial claims of public US companies. It does not explicitly state when not to use it or mention alternatives among siblings, but the specificity makes it adequate.

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