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 only mentions that the results are extracted from SDK source and not invented, which is a reliability claim, but it does not describe any side effects, error conditions, or the nature of the return value (e.g., whether it is a lookup, might be empty, or could fail). This is insufficient 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 a single, compact sentence with no filler. It front-loads the core purpose ('real SDK method(s)') and includes the sourcing detail. It is not verbose, but the phrasing is slightly awkward ('per language extracted...' could be clearer). Overall, it is 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 the absence of annotations, an output schema, and schema descriptions, the description is expected to carry substantial context. It fails to explain the expected input format, what the output looks like, or any dependencies. It does not mention that operationId is required or that language is optional, nor does it clarify what 'one operation' means. The tool is not adequately specified for an agent to call it correctly without further inference.

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

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

Schema description coverage is 0%, so the description must compensate by explaining what language and operationId mean. It does not. The schema only provides an enum for language and a generic string for operationId, but the description never clarifies how to obtain or interpret operationId, nor does it explain the per-language aspect. The description adds no parameter-level value, leaving the agent to guess.

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 returns the actual SDK method(s) for a given operation, per language, sourced directly from SDK source. It distinguishes itself from siblings like get_operation by focusing on SDK method names, but it does not explicitly say what the output format is (e.g., a string, list). The phrase 'never invented by analogy' adds a quality attribute, but the core purpose is understandable.

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 no guidance on when to use this tool versus alternatives such as get_operation or search_knowledge. It does not mention any conditions or contexts where this tool is the right choice, nor does it exclude any scenarios. The only hint is 'never invented by analogy,' which implies reliability but not usage selection.

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 present, so the description carries the burden. It discloses the informational nature of the tool and enumerates output facets (meaning, HTTP status, retryability, remediation, related operations). It doesn't mention edge cases like unknown error codes, but it is reasonably transparent for a read-oriented lookup tool.

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?

A single front-loaded sentence that enumerates exactly what the tool provides. Zero filler; every phrase communicates a distinct piece of useful information.

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

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

For a tool with one required parameter and no output schema, the description is complete enough: it identifies the input and specifies the categories of output. Minor gaps are the lack of an explicit note about read-only behavior or behavior for invalid codes.

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 only declares errorCode as a string with no description or format. The description compensates minimally by saying 'for one error code' — enough to know what to pass, but with no examples, accepted formats, or guidance on how to find valid codes.

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's purpose: explaining an error code by returning its meaning, HTTP status, retryability, remediation, and related operations. The resource is specific and the action is implied by the name and description, though it does not explicitly distinguish itself 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?

The description implies when to use it — for a single error code — but gives no explicit guidance on when not to use it or how it compares to alternatives among sibling tools like get_operation or get_recipe.

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 must carry the behavioral disclosure burden. 'Full detail' suggests a read-only retrieval, but the description never explicitly states that the operation does not modify data, nor does it mention any permissions, rate limits, or side effects. It is a simple get, so the lack of explicit safety disclosure is a minor gap, but still not fully transparent.

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, focused sentence that front-loads the core purpose ('Full detail for one capability') and then enumerates the included content. Every word earns its place; there is no redundancy or padding.

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?

Although the tool is simple (one parameter, no output schema), the description fails to define the input parameter, which is critical for correct invocation. It also does not state the read-only nature or any prerequisites. Given the absence of annotations and schema descriptions, the description is incomplete for an agent to use confidently.

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

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

Schema description coverage is 0%, so the description must compensate by explaining the 'capability' parameter. It merely says 'one capability' without specifying whether it is a name, ID, slug, or another identifier, nor its format or valid values. This leaves the agent without enough information to construct a correct request.

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 'full detail' for a capability, listing its operations, errors, webhooks, and recipes. This distinguishes it from siblings like get_operation (which targets a specific operation) and get_webhook_contract (which targets a webhook). The verb 'get' and resource 'capability' are specific and unambiguous.

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

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

The description implies usage when a comprehensive view of a single capability is needed, but it never explicitly contrasts with sibling tools like get_operation or get_recipe, nor does it state when not to use this tool. The distinction is inferable from the name and sibling set, but no explicit guidance is provided.

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 behavioral burden. It explicitly discloses the network timeout behavior ('never blocks beyond a short timeout'), which is valuable. It implies a read-only operation but doesn't explicitly state side effects or error behavior; however, the timeout note adds meaningful transparency beyond the schema.

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

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

Two sentences with no fluff. The core output (local vs remote, update availability, last check) is front-loaded, and the timeout behavior is appended as useful clarification. Every clause 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 zero-parameter tool with no output schema, the description covers the essential information an agent needs: what status fields are returned and the network behavior. It doesn't specify exact output formatting, but without an output schema, this is acceptable given the simplicity.

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

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

The tool has zero parameters, so the baseline is 4. No parameter meaning is needed, and the description correctly focuses on what the status returns rather than any input semantics.

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

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

The description clearly states the tool reports local vs remote knowledge versions, update availability, and last check time. It uses a specific verb ('get') and resource ('knowledge status'), and the content distinguishes it from siblings like update_knowledge or search_knowledge.

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 its use for status checks but provides no explicit guidance on when to prefer it over alternatives like update_knowledge or get_capability. Context is clear enough for an agent to infer, but no exclusions or alternatives are named.

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 must carry the entire burden of behavioral disclosure. It mentions that the tool returns 'full detail' including SDK mapping, which is useful, but it does not explain whether the operation is read-only, whether it requires authentication, what happens if the operationId is invalid, or the structure of the response. For a tool that likely performs a read operation, this lack of behavioral context is a notable gap, but the description at least gives a hint of the output content.

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, concise sentence that is easy to scan and quickly conveys the main purpose. It is not overly verbose, and the key detail (SDK mapping) is included without excessive fluff. It could arguably be more front-loaded with an explicit statement of the resource, but overall it is appropriately sized.

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 (one parameter, no output schema, no annotations), the description is insufficiently complete. An agent lacks critical information such as how to obtain a valid operationId, what the 'full detail' includes beyond SDK mapping, and the nature of the response (e.g., errors, not found cases). The description is a minimal stub that leaves too much to inference.

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 0%, meaning the description must compensate for the lack of parameter documentation. The description only mentions 'per-language SDK mapping' which indirectly relates to the output, not the input parameter. It does not explain what operationId represents (e.g., a string identifier of a specific API operation), format expectations, or how to obtain it. Since there is only one parameter, the description adds minimal semantic value beyond the schema's type 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?

The description clearly identifies the resource (a public API operation) and the kind of information returned (full detail, including per-language SDK mapping). It is more specific than just the name, and while it doesn't explicitly distinguish from siblings, the focus on 'operation' and 'SDK mapping' helps set it apart from tools like get_capability or get_recipe.

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 the tool is for retrieving details about a specific operation, but it does not state when to use it versus alternatives like search_knowledge or explain_error. There is no explicit guidance on when not to use it or what prerequisites exist (e.g., needing an operationId). The context is somewhat clear but not fully elaborated.

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 lists content areas (capabilities, flow, errors, webhooks) but does not state whether the operation is read-only, what the response shape looks like, what errors might occur, or any side effects. The description adds minimal behavioral context beyond the listed topics.

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, compact sentence with no filler, and the concept of a 'full integration pattern' is front-loaded. However, the sentence is under-specified despite its brevity, and the trailing list of components reads more like content tags than structured guidance. It is concise but not fully effective.

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

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

The tool has one undocumented parameter, no output schema, and no annotations. The description hints at a rich response (capabilities, flow, errors, webhooks, etc.) but does not explain the input identifier, return format, or error handling. An agent would struggle to invoke this tool correctly with the information provided.

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 has one parameter, recipeId, with no description and 0% schema description coverage. The description does not mention recipeId at all, so an agent cannot determine what value to pass (e.g., an ID, a slug, a path) or how it affects the returned integration pattern. The description completely fails to compensate for the undocumented 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 identifies the tool as delivering 'a full integration pattern' and lists its components, which gives a general sense of what is returned. However, it lacks an explicit action verb such as 'retrieves' or 'returns,' and the meaning of 'recipe' is only inferred from the tool name. It is not a tautology, but the purpose is somewhat vague.

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 no guidance on when to use this tool versus alternatives like get_capability, get_operation, or get_webhook_contract. There is no mention of conditions, exclusions, or expected usage scenarios, leaving the agent to guess the appropriate 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?

With no annotations provided, the description carries the full burden. It does disclose the content and the optional filtering behavior, which implies a read-only retrieval. However, it does not explicitly state read-only semantics, potential authentication requirements, rate limits, or any side effects. The description adds value by specifying the exact data returned, but leaves the operational profile implicit.

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 front-loads the core purpose ('full delivery contract') and immediately lists key contents, then introduces the optional event-specific detail. No redundancy or filler; every phrase 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 get tool with one optional parameter and no output schema, the description is largely sufficient. It tells the agent what it returns and how the parameter affects the result. It lacks examples of eventType values and explicit error conditions, but given the low complexity, these are minor gaps.

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

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

The schema has one parameter (eventType) with zero description coverage. The description partially compensates by explaining that providing it yields detail for one specific event type, while omitting it yields the full contract. However, it does not define valid event type values or format, leaving the agent to infer or discover them elsewhere.

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 webhook delivery contract, specifying the exact contents (headers, HMAC formula, timestamp/ordering rules) and the optional event-specific detail. This is a specific verb-resource pairing that is distinct from all sibling tools, which target capabilities, knowledge, operations, SDKs, errors, recipes, and integration planning.

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: omit eventType for the full contract, provide it for a specific event type. It doesn't explicitly name alternatives, but the sibling tools are unrelated, so the context is clear. The guidance on parameter behavior is effective but not explicit about when to choose this over others.

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 mentions the tool resolves a recipe and expands it into a plan, but does not disclose whether it mutates state, has side effects, requires prior steps, or what the exact output format is. The lack of any behavioral detail beyond the high-level process is a significant gap.

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, tightly packed sentence with no filler. It front-loads the core action and lists the key output components efficiently. Every word contributes 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 2-parameter tool with no output schema and no annotations, the description provides a reasonable high-level overview but lacks detail on expected return format, possible failure modes, and any dependencies on the surrounding knowledge system. Siblings like get_knowledge_status suggest prerequisites, but none are mentioned. It is functional but not fully self-sufficient.

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

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

Schema coverage is 100%: both goal and recipeId have clear descriptions. The tool description adds context about the overall process (e.g., 'closest by search') but does not add meaningful parameter-specific detail beyond the schema. Since coverage is full, a 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 the action: given a goal, it resolves a recipe and expands it into a concrete plan with specific components (operations, SDK calls, errors, webhooks). This differentiates it from siblings like get_recipe (which just fetches a recipe) and validate_integration_plan (which validates, not plans).

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 it handles the recipe resolution internally, but does not explicitly state when to use this tool versus alternatives like get_recipe or search_knowledge. There is no guidance on prerequisites (e.g., whether knowledge must be loaded) or scenarios where a sibling would be more appropriate.

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

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

With no annotations present, the description carries the full behavioral burden. It does disclose the search strategy and fallback order (exact ID > alias > lexical), which is genuinely useful. But it omits other behavior an agent would need: result format, result limits, match highlighting, and how strictly 'exact id' matching is applied.

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?

A single sentence that front-loads the search strategy (exact ID > alias > lexical) followed by the scope. No filler, no redundant restating of the name, and every clause carries 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?

There is no output schema, so the description should clarify what the tool returns)Skip; it does not. It also doesn't explain limit behavior or whether results are scored/deduplicated. However, for a read-only search tool, the scope and matching behavior are the most important context and those are covered.

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 low (only query is described in the schema). The description partially compensates by enumerating the searchable kinds and the search precedence, but it never explains the limit parameter's semantics (e.g., default number of results, maximum, pagination). It adds less than it could for the uncovered parameters.

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

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

The description uses a specific verb ('search') with a clear resource and scope, listing the eight knowledge domains it spans. It is immediately distinguishable from the get_* siblings, which retrieve a single known item, because this tool is explicitly a cross-domain lookup with a defined search strategy.

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 the tool is for cross-cutting lookup across domains, especially when you may not know the exact item type or ID. However, it never states when to prefer this over a sibling get_* tool, and it does not mention whether to use it for alias-based lookup or only as a last resort.

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 behavioral burden and does so well. It discloses that the update is data-only, verifies via SHA-256 hash and schema before activation, requires explicit consent, and never updates the MCP engine itself. This gives an agent a clear safety and side-effect profile.

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

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

Three short sentences, each carrying essential information: action, verification/safety, and critical prerequisite. No filler or redundant restatement of the tool name.

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

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

Given the tool's simplicity (one required parameter, no output schema, no nested objects), the description is complete enough for correct invocation. It explains what happens, how safety is ensured, the required consent flag, and what the operation does not affect.

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 already describes the consent parameter completely and marks it required, so the description adds little new parameter-level meaning. It reinforces the consent gate but does not introduce additional format, values, or behavioral details 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 states a specific verb and resource: 'Downloads and applies the newer remote knowledge bundle.' It also clarifies scope with 'data only' and 'Never updates the MCP engine itself,' which distinguishes it clearly from sibling tools like get_knowledge_status or search_knowledge.

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 the tool is used to apply the latest remote knowledge bundle and requires consent, but it does not explicitly state when to use it over alternatives or when not to use it. No exclusions or alternative tool references are provided.

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 must carry the behavioral burden. It discloses that the tool 'flags unsupported claims' (a read-only action), but it does not state whether it modifies data, requires authentication, or describes the exact output format. The examples give some insight but not comprehensive behavioral context.

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

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

The description is a single, well-structured sentence that front-loads the action ('Checks a proposed plan') and then adds illustrative examples. It is concise with no wasted words, effectively balancing detail and brevity.

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?

Without an output schema, the description should hint at return values. It implies the tool returns a list of flagged issues ('flags unsupported claims'), but it does not specify the response structure, whether it returns a report or throws an error, or any prerequisites. For a validation tool, this is adequate but leaves some ambiguity.

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

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

Schema description coverage is only 50% (operationIds lacks a schema description). The description compensates by explaining both parameters: 'free-text claims' for claims and 'operationIds' for the array of identifiers. It adds semantic meaning beyond the schema, though it could be more explicit about operationIds format or constraints.

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

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

The description clearly states the tool's purpose: to check a proposed plan against known gaps and platform invariants, with explicit examples of unsupported claims. It uses a specific verb ('checks/flags') and identifies the resource (proposed plan), and the context of validating a plan distinguishes it from sibling tools like plan_integration or search_knowledge.

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

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

The description implies usage (when you have a plan to validate) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It lacks phrases like 'use after plan_integration' or 'instead of search_knowledge', so guidance is only implicit.

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