Alter Onboarding

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

With no annotations, the description carries the full burden, and it does substantial work: it discloses subset limitations, alternate-URL behavior for out-of-subset pages, flexible spelling/redirect handling, and omit-slug-to-list behavior. Return format and error behavior are not described, but those are minor for a doc-fetching 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?

Three dense sentences front-load the core action first, then cover edge cases. There is no filler; every clause adds operational 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 tool with one optional parameter and no output schema, the description covers the invocation contract well: subset scope, URL fallback for out-of-subset docs, accepted formats, and list behavior. The only notable gap is not stating what the returned page content looks like, but the context makes this a minor omission.

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

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

Schema coverage is 100%, but the description adds significant value by enumerating the accepted slug forms (bare slug, leading slash, #anchor, full URL, older redirecting path) and the omit-to-list behavior. This removes practical ambiguity about how to supply the single 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 names the verb ('Fetch'), the specific resource ('bundled onboarding SUBSET of the Alter docs'), and the key ('slug'), so the purpose is immediately clear. It does not explicitly differentiate from sibling tools by name, but the 'bundled subset' scope statement provides enough distinction.

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 clearly identifies the intended use case (fetching from the bundled onboarding subset) and gives explicit guidance for pages outside the subset: they are not missing and should be read at the docs-site URL. This is an actionable exclusion, though it does not name sibling alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the data is fetched 'live from Alter's provider-spec catalog' and that the response includes the spec's source and freshness, which is useful dynamic-behavior context. It does not mention edge cases like invalid operation ids, but for a read-only lookup tool the disclosed behavior is reasonably complete.

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 wasted words. The first sentence front-loads the tool's core value and enumerates the returned fields; the second gives the essential prerequisite. Every clause contributes meaningful 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 metadata-fetch tool with no output schema and no annotations, the description tells the agent what will be returned, where the data comes from, and how to obtain the required operation_id. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents provider_id, operation_id, and kind well. The description adds extra semantic value by specifying that operation_id comes from list_operations and gives an example format. This goes beyond the schema's generic description without duplicating it.

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 opens with a specific verb ('Fetch') and a precise resource ('one provider API operation's full contract'), then enumerates exactly what that contract contains: method, path, parameters, request/response schemas, plus source and freshness. It also distinguishes itself from list_operations by explicitly telling the agent to get operation ids there first.

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 a clear prerequisite and sequencing instruction: 'Get operation ids from list_operations first.' This tells the agent when the tool is appropriate relative to a key sibling. It does not explicitly list exclusions or alternative tools like fetch_doc, but the prerequisite plus the concrete output scope provides solid usage guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the interactive behavior (lists phases, returns flows/hint, expects a follow-up call) and the heuristic hint to classify the use case. However, it leaves ambiguity about whether the tool actually modifies the integration or is purely informational—the phrase 'Begin or change' suggests action but the described behavior (returning phases/plans) implies advisory. Permissions or side effects are not mentioned.

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

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

Three sentences, front-loaded with purpose, then a compact step-by-step usage pattern. No redundancy or filler. The structure is efficient and easy to follow.

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

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

No output schema exists, so the description explains expected returns for each invocation mode: phases, flows with hint, and full plan. It also advises sequential execution. It does not cover error cases or prerequisites, but for an interactive guidance tool this is sufficiently complete to get an agent started.

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

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

Schema coverage is 100% with descriptions for each parameter, so the baseline is 3. The description adds sequential meaning beyond the schema: it explains that `phase` determines which flows are returned, `goal` is the flow id you classified, and how the parameters are used across calls. This relationship is not captured in the schema and helps the agent use the parameters correctly.

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?

States a specific purpose: 'Begin or change an Alter integration.' It is clearly the entry point for starting or modifying an integration, and the description of phases/flows distinguishes it from siblings like list_phases or next_step. The verb and resource are explicit enough for an agent to understand the core function.

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

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

Provides explicit multi-step guidance: first call with no args to list phases, then with `phase` to get flows and a heuristic hint, then with `goal` for the plan. Also advises sequential execution for multi-flow use cases. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a full when/when-not comparison.

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, and it delivers: it discloses live sourcing, return contents (ids, methods/paths, source, freshness), the auto-detection ambiguity, and instructs agents to read structuredContent instead of prose. This goes well beyond a generic listing description.

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

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

Three sentences, front-loaded with purpose, no filler. Each sentence adds distinct value: what the tool lists, what it returns, how to handle `kind`, and how to read results. Excellent structure for an agent-facing definition.

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

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

Given the rich output schema and fully documented parameters, the description covers everything an agent needs: purpose, key behavior, disambiguation, and the preferred machine-readable output path. No critical operational detail is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining `kind` semantics (auto-detect vs. explicit oauth/managed) and giving a concrete provider example. The remaining parameters are already fully documented 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 uses a specific verb ('List') and resource ('API operations a provider exposes'), with a concrete example ('what can I call on google?') that makes the tool's purpose immediately obvious. It also distinguishes this from sibling tools like list_providers or get_operation_schema without needing to name them.

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?

Gives clear contextual guidance: omit `kind` for auto-detection and expect to be asked for it when both oauth and managed exist. It doesn't explicitly state when to prefer an alternative like get_operation_schema, but the context is clear enough for correct 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?

With no annotations provided, the description carries the burden of behavioral disclosure. The verb 'List' clearly indicates a read-only, non-destructive operation, and the mention of 'what each is for' sets expectations for informational output. No auth or side-effect concerns are plausible for a zero-parameter listing, so the description is adequately 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 concise sentence with the action verb and resource front-loaded, followed by the explicit phase names and the purpose of the output. Every word earns its place, and there is no redundancy or filler.

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

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

For a simple, zero-parameter, informational list tool, the description fully covers what the tool does and what the response will convey. No output schema or annotations exist, but none are needed at this level of complexity; an agent can confidently invoke this tool based solely on the description.

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, so the description does not need to document parameter semantics. It still adds meaningful context about the phases being listed, which helps an agent understand the tool's purpose even without 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 names a specific resource ('lifecycle phases this server serves') and enumerates the phases (setup, modify), plus explains that each phase's purpose is included. This clearly distinguishes it from sibling tools like list_operations and list_providers, which target different resources.

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 use when an agent needs to understand the server's lifecycle phases, but it does not explicitly state when to choose this tool over alternatives or mention any exclusions. The context is clear enough for an agent to infer, but no explicit guidance is given.

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 full burden. It discloses that the tool lists all matching providers and indicates result fields (source and freshness), which is solid behavioral context. However, it does not explicitly state read-only status, pagination, or need for authentication, leaving minor gaps for a list operation.

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

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

The description is three short sentences with no filler. It front-loads the primary purpose, then states the optional filter, then provides a routing instruction, each sentence earning 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 one-optional-parameter list tool with no output schema, the description covers the result scope (all providers, with source and freshness), the filter, and the recommended next step. It doesn't detail the exact provider identifier format needed for the next call, but that is a minor omission given the simple domain.

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 `kind` already documented as an enum with a definition in the schema. The description only adds 'Optionally filter by `kind`,' which reinforces the parameter's role but doesn't add substantive meaning beyond the schema. Baseline 3 applies.

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 opens with a specific verb and resource: 'List every provider with an ingested API spec in Alter's provider-spec catalog,' which precisely states the tool's scope. It also distinguishes itself from sibling list_operations by explicitly naming it as the next step. This is far beyond a tautology.

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

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

'Start here, then call list_operations for a provider's operations' gives an explicit sequence and names the correct sibling for the next task. It also notes the optional kind filter, clarifying the main decision point for narrowing the result. Clear when-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?

With no annotations, the description carries the full burden for behavioral disclosure. It states the output scope (skills and their phases) and clarifies that reading a full skill happens via a separate resource. However, it does not explicitly state that the operation is read-only, whether auth is needed, or what the response shape looks like.

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 the primary action, and every phrase adds value. The first sentence states purpose and output; the second gives an actionable pointer to related functionality without filler.

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

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

This is a simple, parameterless listing tool, and the description covers what is listed and where to go for full skill content. It does not need to explain return values since there is no output schema. Slight gap: it could explicitly distinguish itself from the many sibling 'list_*' tools, but the phase detail already does this implicitly.

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 takes zero parameters, and the schema coverage is 100%. The baseline for no parameters is 4; the description appropriately focuses on the tool's behavior rather than inventing parameter details that do not exist.

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 ('List'), names the resource ('guidance Skills'), scopes it to the server, and specifies the distinguishing property ('with the phase each serves'). It is easily differentiated from sibling tools like list_operations or list_phases.

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 clearly conveys that this tool is for listing skills, and the second sentence points to the appropriate mechanism for reading a skill's full content via a resource URI. However, it does not explicitly mention when to prefer another sibling list tool (e.g., list_phases) over this one.

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?

Without annotations, the description takes on the burden and adds non-obvious behavior: it instructs a detect-then-run sequence and reveals that the design step returns a complete starter ALTER_INTEGRATION.md. It stops short of detailing the full return object or error cases, but the disclosed workflow traits are valuable.

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 tight sentences, each earning its place: purpose, argument semantics, and special behavior. No filler or repetition of schema text.

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 two-parameter read-style navigation tool with no output schema, the description is nearly sufficient: it explains invocation, argument conventions, and the one special step that returns extra content. It would benefit from stating the shape of the returned step, but the detect/run references imply the fields.

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

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

Schema already covers both parameters at 100%, and the description adds the crucial 'omit after for the first step' convention plus clarifies goal as a flow id. This goes beyond the schema, meriting more than the baseline.

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 opens with an explicit verb-resource pair ('Return the next step for a flow'), clearly distinguishing it from sibling list_phases or get_operation_schema. The goal parameter enum reinforces that it is a step navigation tool.

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

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

Provides direct operational guidance: pass goal and after, omit after for first step, and run detect before run with a skip condition. It does not explicitly name alternatives or exclusion criteria, but the workflow instructions make the intended use unambiguous.

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 burden, and it largely does: it frames the tool as a read-only grammar lookup, discloses that data is live from the deployed backend, and describes the returned content. It does not explicitly state 'no side effects' or error behavior for unknown rule types, but the query-style semantics make this a minor 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?

Two dense sentences front-load the core value and then give precise call patterns. The workflow prose mentioning fetch_doc is a little verbose but earns its place by connecting to the broader authoring workflow.

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 single optional-parameter reference tool with no output schema, the description is complete: it states what the tool is, what it returns, the exact call patterns, and the surrounding workflow. Nothing critical is missing for an agent to select and 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?

The schema already describes rule_type well with 100% coverage, so the baseline is 3. The description adds value by explaining the two invocation modes—no argument vs. passing rule_type—and giving concrete examples like content_match, going beyond the schema's bare 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 identifies the tool as the authoritative grammar of Alter's policy language, listing the exact content it exposes (rule types, JSON body schema, caps, authorable levels, examples, fail-closed semantics). It distinguishes itself from documentation-style siblings by emphasizing that it is live from the deployed backend, so an agent can tell it apart from fetch_doc.

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 gives explicit invocation guidance: call with no arguments for the overview, pass rule_type for a specific grammar. It also states when to use it—before authoring rules with alter policy rules create—and even references the relevant fetch_doc workflow.

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 transparently states that the tool returns code snippets rather than performing an action, which is useful. However, it does not disclose details like whether the output is a complete file, whether it makes external requests, or how the goal values change the returned wiring.

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 that front-loads the action and output, then includes the key differentiators: install, client init, request, language, and goal. Every word 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 two enum parameters and no output schema, the description provides enough information to understand what will be returned: SDK wiring covering install, client init, and request. It is slightly incomplete because it does not clarify expected output shape or integration expectations, but the schema covers the parameters 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 description coverage is 100%, so the schema already documents the language and goal parameters. The tool description only restates 'for a language and setup goal' and adds no additional semantic detail about how each specific goal affects the returned integration code.

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 ('Return') and names the resource ('Alter SDK wiring') with concrete contents: install, client init, and request. It clearly states the purpose for a language and setup goal, but does not explicitly differentiate it from the sibling tool sdk_pattern.

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 the tool: when a developer needs SDK integration code for a given language and goal. However, it does not provide explicit guidance on when to prefer this tool over alternatives like sdk_pattern, get_started, or fetch_doc.

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 does clarify that the output is a 'runnable' pattern and explains what each pattern represents (e.g., 'zero-egress proxy_request + HITL'), which adds some transparency. But it doesn't disclose side effects, authentication requirements, or whether this merely returns text versus executing anything.

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 zero waste. The main action and outputs are front-loaded, and the usage ordering is a separate, concise sentence. Every word 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 two-parameter tool with no output schema, the description covers the tool's purpose, parameter semantics, and the critical prerequisite (use after `sdk_integration`). It doesn't provide an example return value, but that's not strictly necessary for correct invocation given the explicit pattern descriptions.

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 baseline is 3. The description goes beyond the schema by explaining the meaning of each `pattern` enum value ('zero-egress proxy_request + HITL', 'call as an end user via their delegated grant', 'the operator-side delegation step'), which materially helps an agent select the correct parameter. The `language` parameter gets no extra semantics, but its values are self-explnatory.

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 ('Return') and resource ('runnable Alter SDK call pattern') and enumerates the three pattern options with brief explanations. It's clear what the tool does, but it doesn't explicitly differentiate from sibling tools like get_started or fetch_doc; rather it positions itself relative to sdk_integration.

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 usage context: 'Use AFTER `sdk_integration` has wired the client.' This clearly tells an agent when to call it. However, it doesn't mention when not to use it or name direct alternatives, which would justify a 5.

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 communicates that the tool is a mapping/lookup operation, which implies no mutation, but it does not disclose behavior on unknown errors, whether any network/service call is involved, or what the returned remediation looks like.

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, front-loaded sentence with no wasted words. It includes the essential input and outcome 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?

The tool is simple and the schema documents the parameters well, but the description does not clarify whether at least one parameter is required, whether both can be supplied simultaneously, or what the return value looks like. Since there is no output schema, some return/behavior guidance would improve completeness.

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

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

Schema description coverage is 100%, with both 'error' and 'exit_code' already described. The description adds only that either an exit code or error message may be mapped, which is a mild semantic hint but not extra detail 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 ('Map'), a specific input class ('@alter-ai/cli exit code or error message'), and an outcome ('remediation'). This clearly distinguishes the tool from the sibling documentation and operation 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 clearly implies when to use the tool: whenever the agent encounters a @alter-ai/cli exit code or error message. It does not explicitly mention alternatives or exclusions, but the triggering condition is clear enough for routing.

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. The explicit statement 'Guidance only — you run the commands' clearly discloses that the tool does not execute anything and only returns guidance. It also states the output type ('copy-pasteable recipe'), making the tool's behavior 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 two sentences with no filler. The action and resource are front-loaded, each scenario is defined inline, and the second sentence adds a critical clarification about the tool's non-executing nature. Every part 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 one-parameter tool with no output schema, the description covers what it returns (copy-pasteable recipe), how the parameter selects behavior (two scenarios), and what it will not do (run commands). An agent has all necessary information to select and invoke this tool correctly.

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

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

The tool description adds substantial meaning beyond the input schema: it explains that `first-call` verifies code↔design mapping, an audit row, and attribution, while `per-user-isolation` verifies two users under different credentials and cross-user rejection. The schema only lists the enum values, so this is genuine added value for choosing the right scenario.

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 and resource: 'Return a copy-pasteable recipe to VERIFY an integration works.' It also enumerates the two distinct verification scenarios, making it unmistakably different from sibling documentation/list tools. An agent can identify this as the verification-recipe tool without opening the schema.

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 clear context for when to use it: when you need to verify an integration, with two named scenarios covering common verification needs. However, it does not explicitly contrast with sibling tools like troubleshoot or get_started, nor does it 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.