Alter Onboarding

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the entire published docs site is bundled, skill pages are included, multiple URL/slug forms are accepted, and omitting the slug lists every page. This is more transparent than typical fetch descriptions, though it does not cover errors or return details.

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

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

Three sentences, each carrying useful information, with the core action front-loaded. No filler or redundant phrasing. The format flexibility and list behavior are packed into a compact, readable structure.

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 fetch tool with no output schema and no annotations, the description covers the main decisions: what to pass, what formats are accepted, and what happens if nothing is passed. It does not state the return payload shape, but for a doc-fetch tool 'can be read in-band' implies the content is returned. The only real gap is explicit routing to search_docs for unknown slugs.

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 describes the slug as a doc slug with one example. The description adds significant meaning: accepted input forms (bare slug, leading slash, #anchor, full URL, older redirects) and the default behavior when the slug is omitted. This substantially enriches the parameter semantics 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 action and resource: "Fetch any page of the Alter documentation by slug." It distinguishes itself from sibling search_docs by emphasizing retrieval via a known slug/URL, and it even covers the list-every-page fallback. The resource scope is 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 clearly implies this tool is for fetching known documentation pages, especially when you have a slug, URL, or redirect. However, it does not explicitly mention when not to use it or name alternatives like search_docs for discovery. The guidance is useful but mostly implicit.

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 present, so the description carries the behavioral burden. It discloses that the tool is interactive, requires the agent to classify the use case itself, and returns a heuristic hint rather than a final answer. It does not state whether the tool mutates state or describe the return structure, but for a planning tool the disclosed behavior is sufficient.

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-load the tool's purpose, then give a compact decision tree for how to use it. Every sentence earns its place and there is no 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 tool with no output schema or annotations, it explains the full calling sequence and the agent's responsibility in choosing goal. It could be more explicit about what the no-arg response contains beyond phases and how use_case is used, but the essential guidance is present.

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 the baseline is 3, but the description adds interaction semantics: phase is the first refinement, goal is the second call after self-classification, and use_case is relevant to deciding whether multiple flows must be run sequentially. This goes beyond the enum labels and property 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?

States a concrete action, 'Begin or change an Alter integration', and describes a phased return (phases → flows + hint → plan), so an agent knows this is an integration onboarding/planning entry point. It does not explicitly distinguish itself from sibling list_phases, whose name overlaps with the no-arg behavior, so not a 5.

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 an explicit usage sequence: call with no args to list phases, then with phase to see flows, then classify and call again with goal; it also tells the agent to handle multi-flow use cases sequentially. It lacks explicit when-not-to-use or alternative routing to siblings, so not 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, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the design step also returns a complete starter ALTER_INTEGRATION.md, and it instructs the agent to run detect before run, which implies the step includes commands. These details go beyond a generic 'returns the next step' and give the agent actionable knowledge about side effects and outputs.

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

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

The description is three sentences with no redundancy. The core purpose is front-loaded, followed by precise usage instructions. Every sentence earns its place: the first states the purpose, the second explains parameter handling, and the third gives the detect/run rule and the extra design step behavior. No unnecessary words 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?

The description covers the tool's purpose, parameter usage, and key behavioral notes (detect/run sequence and the design step's extra return). Since there is no output schema, the description could have described the step's structure more explicitly, but it gives enough context for an agent to call the tool and handle the result correctly. The lack of error-case or edge-case detail prevents a perfect score.

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 the schema descriptions already cover the parameters (100% coverage), the description adds value by clarifying that 'goal' is a flow id and by instructing the agent to omit 'after' for the first step. This is not present in the schema and directly affects how parameters are used, so the description enriches the schema semantics rather than just repeating them.

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 clear verb-object statement, 'Return the next step for a flow,' and immediately identifies the two required inputs (goal and after). It also clarifies the 'goal' parameter as a flow id, which is a meaningful addition. While it does not explicitly compare to siblings, the action is specific enough that no sibling appears to overlap with this purpose.

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

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

The description provides concrete usage instructions: how to pass parameters (including omitting 'after' for the first step) and how to consume the result ('Run each step's detect command FIRST and skip the run command when detection passes'). It does not name alternatives or say when not to use this tool, but the guidance is actionable and specific, so it earns a 4 rather than a 3.

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 does well: it discloses that content is live from the deployed backend, that no-arg returns an overview vs. rule_type returning one grammar, and that fail-closed semantics apply. It does not describe return size, pagination, or error behavior, which keeps it short of a 5.

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?

Front-loaded with purpose and use, and most sentences earn their place by routing the agent. However it is a single dense paragraph that folds in a vocabulary-mapping clause and a long workflow-prose list, which slightly bloats it beyond the core message.

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

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

Given a single optional param, no output schema, and no annotations, the description covers everything an agent needs: what it returns, the two call modes, when to use it, the disambiguation from docs/CLI terminology, and where to find workflow prose. Nothing essential 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the two calling modes (no arguments = overview; rule_type = full grammar for one type) and giving an example value. It does not enumerate valid rule_type values, which would earn a 5.

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 resource (the authoritative grammar of Alter's runtime-policy language) with its scope (every authorable rule type with JSON body schema, caps, levels, examples, fail-closed semantics). An agent can distinguish it from siblings like fetch_doc or get_operation_schema purely from this text, since it names the exact artifact it returns.

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

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

Explicitly says to call it before authoring rules with `alter policy rules create` and to never guess a body shape, and it names alternatives (fetch_doc guides, get_started phase=modify) plus an exclusion (code_owner rules are changed through their file, never with rules update). This is when/when-not/alternatives coverage.

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?

With no annotations, the description carries the behavioral burden. It discloses important behavior for `resolve-ambiguous-grant` ('choose deliberately, never the first, and persist it') and characterizes the output as 'runnable'. It does not describe return format or any side effects, but the description is still meaningfully 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 dense sentence but every clause earns its place: it defines the output, explains each pattern, embeds a caveat for ambiguous grants, and states the prerequisite. It could be better structured, but it is not padded or redundant.

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 tool with no output schema and no annotations, the description covers purpose, pattern selection, and usage sequencing well. It might benefit from an example or explicit return-type detail, but the information an agent needs to invoke it correctly is present.

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 already documents both parameters at 100% coverage, so the baseline is 3. The description adds real semantic value by explaining what each pattern value does (zero-egress + HITL, delegated grant, operator-side delegation, ambiguity handling), which helps an agent pick the correct enum beyond the schema's bare listing.

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 ('Return') and a concrete resource ('a runnable Alter SDK call pattern for a language'), then enumerates the exact pattern variants it covers. It also distinguishes itself from sibling sdk_integration by explicitly tying usage to after that tool has wired the client.

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 usage context with 'Use AFTER `sdk_integration` has wired the client' and explains the meaning of each pattern, which helps an agent choose the right one. It does not name alternative tools it should not be used for, but the conditions for selecting the tool are reasonably explicit.

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 does well: it discloses the search scope, that results include matched sections and snippets, and that it returns best-matching pages rather than full content. It does not cover all possible edge behavior, but it gives enough context for a search 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?

Two compact sentences with no filler: the first states what the tool does and returns, the second gives the exact usage condition plus the recommended next action. 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 search tool with no output schemacars, the description fully covers purpose, scope, return format, when to use it, and what to do next. The parameters are fully documented in the schema)Skip; no essential missing context remains.

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 and provides examples. The description adds context about keyword-based matching and snippet results, but it does not materially extend the schema's parameter meaning beyond what is already present.

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 ('Search'), a precise resource ('every bundled page of the Alter documentation'), and the exact return shape ('best-matching pages with the section and a snippet'). It clearly differentiates this from fetch_doc by its search scope and outcome.

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 explicitly says when to use the tool: 'when a flow step or doc did not point you at the page you need'. It also names what to avoid ('guessing slugs or listing every page') and gives the follow-up action ('then read one with fetch_doc and its slug'). This is ideal routing 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. 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.