spinnaker-mcp

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so safety is largely covered. The description adds genuinely useful context beyond them: a sandboxing constraint (reflection and class instantiation are blocked) that affects what expressions will succeed, which the agent cannot learn from annotations or 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?

Four short sentences, front-loaded with the core action, then usage, then the security caveat, then return shape. No filler or repetition.

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

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

With an output schema present and full parameter documentation plus annotations, the description needn't explain return values. It adds the security caveat and debugging framing, making it nearly complete; only error behavior (e.g., invalid expression, missing execution) is left implicit.

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

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

Schema coverage is 100% and includes SpEL syntax examples (${trigger.parameters.tag}, ${#stage('Deploy').status}), so the schema carries the parameter burden. The description adds no additional meaning about expression format, escaping, or execution_id requirements.

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 verb (evaluate) and resource (SpEL expression) plus the evaluation context (pipeline execution), which is unique among siblings that are all get_/list_/find_/search_ retrieval tools. An agent can immediately tell this is an expression-evaluation tool, not a data-fetch 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?

"Use this to inspect pipeline variables, stage outputs, or computed values during debugging" gives clear usage context and intent. It does not name exclusions or point to alternative tools (e.g., use get_execution instead when only static metadata is needed), so it falls short of 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the return format ('JSON array of matching image objects') and the filterable dimensions, but says nothing about pagination or how 'all Gate finds' limiting behaves when count is omitted.

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

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

Four short sentences that front-load the resource definition before the usage hints and return format. Nothing is redundant, though the final sentence on return format is partly wasted given an output schema exists.

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

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

With a complete input schema, an output schema, and rich annotations, the description only needs to establish purpose and usage, which it does. The gap is minor: no guidance on the closest sibling (get_image_tags) or on result limiting when count is omitted.

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 every parameter including count, query, region, account, and provider is already documented. The description restates three of the filters without adding syntax, format, or default behavior beyond the schema, which matches the baseline of 3.

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

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

States a specific verb and resource with concrete examples (AMIs, GCE images, Docker images) scoped to a cloud provider. It is distinguishable from most siblings, though it never mentions the closely related get_image_tags sibling, leaving that boundary implicit.

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 sentence 'Use this to find images for a deployment or verify which image versions are available' gives a clear usage context. It stops short of naming when-not-to-use conditions or pointing to get_image_tags as the alternative for tags.

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

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

The annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds useful context about the account details available and the pre-deployment verification use case. It does not add much beyond that, such as authentication requirements or limitations on visibility, so with annotations carrying the safety profile a 3 is appropriate.

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 concise sentences with the core operation front-loaded. Each sentence adds useful information about what is returned or when to use it. There is no unnecessary verbosity.

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 rich annotations, an output schema, and a fully described single parameter, so the description mainly needs to state purpose and usage. It does that well. The main missing piece is explicit routing versus list_accounts, which would make selection even clearer.

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?

There is only one parameter, and schema coverage is 100%, so the schema already fully documents the account name parameter. The description reinforces that lookup is by account name but does not add format, constraints, or examples beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: get details for a single Spinnaker account by name. It also lists the kind of data returned, which makes the tool's purpose clear. It does not explicitly name or contrast with the sibling list_accounts tool, so it falls short of the strongest sibling differentiation.

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 a clear use case: verify account configuration or check permissions before deploying. That provides useful context for selecting this tool. However, it does not explicitly say when not to use it or route the agent to list_accounts for account discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is returned, including application metadata, associated cloud accounts, and cluster details, though it does not discuss permissions or error behavior.

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, front-loaded with the core purpose and followed by usage context and return details. Every sentence contributes useful information without repetition 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?

For a simple single-resource read tool with one parameter, rich annotations, and an output schema, the description is complete enough to call correctly. It explains purpose, usage context, and return contents without needing to restate schema or output-schema details.

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?

There is one parameter and the schema description coverage is 100%; the schema already explains that 'application' is the application name as registered in Spinnaker. The description adds no syntax or format guidance beyond the schema, so the 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 states a specific verb and resource: get detailed information about a single Spinnaker application. It clearly distinguishes the tool from list_applications by emphasizing a single application, and from sibling get_* tools by naming application-level contents such as accounts, clusters, and custom attributes.

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 a clear usage context: inspect an application's configuration before modifying pipelines or infrastructure. It does not explicitly name alternatives or exclusions, such as using list_applications first to discover application names, so it falls short of 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the content dimension (cluster metadata, server groups, load balancers, instance counts), but that overlaps with the output schema rather than adding behavioral context like auth requirements or missing-cluster behavior.

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, front-loaded with the core action and scope, with zero filler. Minor redundancy in restating the return payload that the output schema already defines.

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

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

With annotations, a fully documented schema, and an output schema, the description supplies enough for correct invocation. Only the missing contrast with list_clusters and empty/missing-cluster behavior keep it from a 5.

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

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

Schema coverage is 100% with each parameter described, so the schema carries the parameter burden. The phrase 'by account and cluster name' slightly reinforces the composite key but adds no format or edge-case detail (e.g., wildcard or case sensitivity for cluster_name).

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 verb and resource ('Get details for a specific cluster') and scopes it to a Spinnaker application keyed by account and cluster name. It implicitly contrasts with list_clusters via 'specific cluster,' but never names the sibling, so an agent must infer the 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?

'Use this to inspect server groups, load balancers, and instance counts within a cluster' gives implied usage, but there is no explicit when-not guidance or reference to the obvious alternative (list_clusters) for enumerating clusters.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the description doesn't need to restate safety. It adds genuinely new behavioral context: the output is JSON and, importantly, instance-authored text that must be treated as data rather than instructions — a real prompt-injection disclosure not derivable from any structured field. It omits operational edge cases such as output truncation or what happens when an instance is stopped.

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

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

Four short sentences, front-loaded with the purpose, then usage, then output format, then the safety caveat. The sentence listing required parameters is partly redundant with the schema's required array, a small amount of non-earning 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?

With annotations covering the safety profile and an output schema covering return values, the description needs only purpose, preconditions and caveats, all of which are present. Minor gaps remain around size/truncation limits and behavior for non-running instances, which matter for a log-retrieval tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the optional provider. The description only restates that account, region and instance ID are required, adding nothing about formats or how provider affects resolution — baseline 3.

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

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

States a specific verb and resource (console output / boot log) scoped to a single compute instance, with a parenthetical that clarifies what the data actually is. An agent can immediately distinguish this from get_instance, which returns instance metadata rather than boot logs.

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?

"Use this to debug instance startup failures or inspect early boot messages" gives a concrete triggering context rather than an implied one. It doesn't name an alternative tool or a when-not-to-use case (e.g. use get_instance for state/metadata instead), so it falls short of the explicit routing seen in top-tier definitions.

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

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

Annotations already declare read-only/idempotent, so the description focuses on non-obvious behavior: the default payload is a compact summary, the full JSON is 'often hundreds of KB'. That size warning is exactly the kind of cost disclosure annotations cannot carry, and the summary field enumeration lets the agent reason about what it will receive.

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 the core action and default behavior, then the rationale and the alternative. The long inline enumeration of summary fields is dense but functional; it could be tightened without losing meaning.

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?

An output schema exists so return values needn't be re-explained, and the description still covers the only decision an agent must make (compact vs full) plus where the required ID comes from. Nothing needed to invoke it correctly 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 goes beyond the schema's one-liner by explaining the practical consequence of summary=false (huge payload) and what the summary branch contains. It doesn't add format or syntax detail for execution_id beyond echoing 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?

States a precise verb+resource plus scope ('one pipeline execution by ID') and immediately distinguishes itself from sibling retrieval paths by describing the compact default payload. An agent can tell it apart from list_executions/search_executions without opening either 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?

Gives concrete user questions it answers ('why did my deploy fail', 'is it waiting on me') and explicitly names the sibling tools that supply the execution_id. It also sets the escalation rule: only pass summary=false when the full JSON is truly needed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds little beyond confirming the lookup is keyed by account/region/name and noting that the response contains the rule set; it does not mention errors when the rule is absent or ambiguity handling when names collide across VPCs (that only appears in 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?

Three short sentences with the core identity and then usage context front-loaded; no filler. The closing sentence about JSON return is mildly redundant given an output schema exists.

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

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

With annotations covering safety, a full output schema, and 100% parameter descriptions, the description supplies what an agent needs to select and call it. Missing only explicit sibling routing (list_firewalls for enumeration) and not-found behavior.

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 all five parameters including provider default and vpc_id disambiguation are already documented. The description merely restates the three required keys and adds no format or edge-case semantics, making baseline 3 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?

States a specific verb (get) and resource (a specific firewall rule / security group) plus the three identifying keys, and the term 'specific' implicitly separates it from list_firewalls. It does not explicitly name the sibling, so differentiation is inferable rather than stated.

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?

'Use this to inspect inbound/outbound rules and associated resources' gives a clear usage context for a lookup-by-identity call. There is no when-not guidance or explicit pointer to list_firewalls for enumeration, so it stops short of full 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the workflow framing and notes the registry must be registered in Spinnaker, but says nothing about the external registry call's failure modes (missing credentials, unreachable registry) despite openWorldHint=true.

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, purpose first, then usage, then return shape — well front-loaded. The return-shape sentence partly duplicates the output schema but costs little.

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

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

With an output schema, full schema coverage, and rich annotations, the description covers purpose, workflow fit, and return shape. The only meaningful omission is behavior when the external registry is unreachable or unauthenticated.

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 account, provider, and repository are already documented with an example ('library/nginx'). The description adds only the loose phrase 'specified repository' and does not explain the provider parameter's defaulting behavior, leaving the schema to do all the work.

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?

Names a specific verb and resource ('Get available tags for a Docker image repository') and scopes it to Spinnaker-registered accounts. It never names a sibling such as find_images, so the agent must infer the distinction between finding images and listing their tags.

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?

'Use this to list version tags before triggering a pipeline with a specific image tag' gives clear when-to-use context tied to a concrete workflow step. It stops short of naming alternatives or stating when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only a light note that the response is JSON with health indicators, and says nothing about behavior on a missing instance or permission failures. Modest added value given rich annotations.

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

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

Three short sentences, front-loaded with the identifying keys before the use case. The closing sentence about returning JSON is partially redundant now that an output schema exists, so it is not quite waste-free.

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

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

With a full output schema and complete parameter descriptions, the description only needs to supply purpose and usage, which it does. The notable remaining gap is error behavior when the instance ID is unknown, a common case for a point lookup.

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% and all three required parameters carry their own descriptions, so the baseline is 3. The description merely restates that account, region, and instance ID identify the instance, adding no format or disambiguation 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?

States a specific verb and resource ('Get details for a specific compute instance') and names the three identifying keys, which cleanly separates it from get_cluster, get_account, and the list_* siblings. It stops short of explicitly pointing at a sibling, but the resource noun 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?

'Use this to inspect instance health, metadata, launch time, and cloud-specific attributes' gives a concrete reason to call it rather than a vague one. No when-not conditions or alternatives (e.g., using list_server_groups to discover an instance ID) are offered, which keeps it out of 5 territory.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds useful behavioral context by stating that it returns the complete pipeline JSON definition, including stage configurations, which helps set expectations for output.

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 focused sentences with no wasted text. Purpose, usage context, and return content are front-loaded in a logical order.

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 read tool with rich annotations and an output schema, the description is complete enough. It explains the lookup scope, intended inspection use, and the general shape of the returned configuration.

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 both parameters are already documented in the schema. The description restates that lookup uses application and pipeline name but adds no extra semantics such as matching rules or case sensitivity, making baseline 3 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 uses a specific verb-resource pairing: get the full configuration of a specific pipeline, scoped by application and pipeline name. It clearly distinguishes this from sibling list/history tools by emphasizing the complete configuration for one named pipeline.

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 clear usage context: inspect pipeline stages, triggers, and parameters before triggering or modifying the pipeline. It does not explicitly name alternatives such as list_pipelines for discovering pipeline names, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the ordering semantics ('ordered by update time') and the array shape, but since an output schema exists the return-value detail is largely redundant. Adequate but not rich beyond annotations.

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

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

Three short sentences with the purpose front-loaded and no filler. The final sentence about return format is partly redundant with the output schema, keeping it just below maximum.

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?

Purpose, use cases, and ordering are all stated, and the output schema plus annotations cover return values and safety. Nothing an agent needs to invoke it correctly is missing; only explicit sibling routing would improve it.

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 the required pipeline_config_id and the limit (default 10, max 100) documented inline. The description adds no meaning about parameter behavior, so the 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?

States a specific verb and resource ('Get the version history of a pipeline configuration') with the qualifier 'showing past revisions', which clearly separates it from get_pipeline (current config) and list_pipelines. The sibling distinction is implied rather than named, so it falls short of 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?

'Use this to audit changes to a pipeline or compare previous configurations' gives concrete use cases, which is more than most read tools offer. It does not, however, state when NOT to use it or name get_pipeline as the alternative for current state.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description's note about returning JSON records with timestamps, descriptions and status adds a little context, but that is redundant with the existing output schema, and it says nothing about pagination, limits or auth beyond what annotations imply.

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, front-loaded with the purpose and followed by usage and return shape. Efficient overall, though the return-shape sentence overlaps with the output schema and could be trimmed.

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

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

With annotations covering safety and an output schema covering return values, the description supplies the remaining purpose and usage context. It is nearly complete for this read-only getter; only pagination/rate-limit behavior is unaddressed.

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 all five parameters (account, application, cluster_name, server_group_name, provider) are already documented in the schema. The description adds no parameter-level syntax or format detail, so 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?

States a specific verb and resource ('Get scaling activities for a server group') plus the system context (Spinnaker cluster), which clearly separates it from sibling getters like get_cluster or list_server_groups. An agent knows exactly what it is fetching.

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 use it 'to audit recent auto-scaling events ... and diagnose capacity issues', giving a clear when-to-use context. It does not name an alternative tool or state when-not to use it, so it falls short of 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description usefully spends its budget elsewhere: it discloses error behavior ("fail" errors unless exactly one server group exists) and the return type (JSON with the matched server group). It does not say what happens when a non-fail selector matches nothing, which is the remaining behavioral 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?

A single front-loaded sentence that moves from identity to selector semantics to use case to return type, with 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?

For a read-only lookup with an output schema and fully documented parameters, the definition covers purpose, usage, selector semantics and return type. The only material omission is empty-match behavior for selectors other than "fail".

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, and the description still adds non-schema meaning for the least obvious enum value: "fail" errors unless exactly one server group exists. The current/newest and previous/ancestor gloss largely restates the schema's own target description, limiting the lift to a modest increment above 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?

States a specific verb and resource (get one server group of a cluster) plus the distinguishing mechanism: lookup by target selector rather than by name. An agent can tell this apart from list_server_groups or get_cluster from the first clause alone.

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?

"Use this for rollback planning or to find what is live now" gives concrete selection contexts and the phrase "instead of its name" implicitly contrasts it with a name-based lookup. It stops short of explicit when-not-to-use guidance or naming a specific alternative tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds value by previewing the response shape — status, start/end times, retry info, step-by-step execution details — which signals a potentially large payload. It is slightly redundant with the output schema and says nothing about behavior for unknown or expired task IDs.

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 the core action, then usage context, then return shape. No filler or restatement of the title.

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

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

With annotations, a fully documented single parameter, and an output schema, the description covers what the tool does and what comes back. Minor gaps remain around error/expiry behavior for long-running tasks, but nothing needed to invoke it correctly 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?

The single task_id parameter is documented at 100% schema coverage ('Orchestration task ID returned by Spinnaker when an operation is submitted'), so the schema carries the semantics. The description adds nothing beyond that about where the ID comes from or what happens with an invalid ID — baseline 3 for a fully covered single-param 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?

States a specific verb and resource ('Get the status and details of a Spinnaker orchestration task') and enumerates example task types (deploy, resize, rollback, delete), which distinguishes it from sibling pipeline/execution tools implicitly. It never names get_execution or list_executions explicitly, so the sibling differentiation is inferred rather than stated.

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?

'Use this to monitor the progress of a long-running infrastructure operation' gives a clear trigger condition for calling the tool. However, no exclusions or named alternatives are provided — an agent must guess whether get_execution, list_executions, or search_executions is the better choice for a related lookup.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile needs no restating. The description adds the return shape (array of account objects with provider type, environment, permissions), but that largely duplicates the existing output schema, and no pagination or empty-result behavior is 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 usage, then return shape — well ordered and largely waste-free. The final sentence earns its place only marginally, since an output schema already exists.

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 list tool with rich annotations and a published output schema, nothing an agent needs in order to call it correctly is missing. Purpose, precondition context, and result shape are all 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema. Baseline 4 applies; the description could only improve by noting that no filtering options 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?

States a specific verb and resource — "List all configured Spinnaker accounts" — and clarifies what an account is (cloud provider integrations). That scope wording implicitly separates it from the singular get_account sibling, though it never names that sibling explicitly.

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?

"Use this to discover available cloud accounts before querying infrastructure or deploying" gives a concrete usage context and ordering relative to other operations. It lacks an explicit exclusion or named alternative, so it stays short of 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds the return shape (JSON array of objects with name, email, accounts, cloud providers), which is useful content context, but the output schema already exists, so this is modest added value rather than rich behavioral disclosure.

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, front-loaded with the core action and followed by usage and return information. Slight overlap with the output schema in the third sentence, but nothing is wasteful.

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

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

With no parameters, full annotation coverage, and an output schema present, the description still supplies the discovery-oriented workflow context an agent needs to place this tool correctly in a sequence. Nothing material 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?

The tool has zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies for a no-parameter tool.

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 clear verb and resource ('List all Spinnaker applications with their metadata') and says it returns all applications, which implicitly separates it from the singular sibling get_application. It doesn't explicitly name a sibling or contrast, so it falls just short of 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?

It gives a concrete usage context: 'Use this as a starting point to discover available applications before querying pipelines or infrastructure.' That tells the agent when to reach for it, though there are no explicit exclusions or named alternatives for when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the grouping behavior (results keyed by account) which is a real behavioral trait beyond the annotations, though it says nothing about ordering, empty accounts, or error cases.

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, front-loaded with purpose, then usage routing, then return shape. The return-shape sentence is partly redundant given an output schema exists, but it is short enough not to be wasteful.

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?

Single required parameter, full schema coverage, rich annotations, and an output schema that carries return details. The description supplies purpose, routing, and grouping semantics, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single 'application' parameter is documented there as 'Application name as registered in Spinnaker'. The description only restates that the application is a Spinnaker application, adding no new semantics such as format or naming 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?

States a specific verb and resource ('List all cluster names') plus the scoping dimension ('for a Spinnaker application, grouped by account'). It also explicitly contrasts with the sibling get_cluster, so an agent can distinguish the two without opening either 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?

Gives an explicit routing rule: 'Use this to discover clusters before drilling into a specific one with get_cluster.' The alternative tool and the condition that selects it are both named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds useful return context ('JSON array of execution summaries with status, timing, and trigger info') and the optional-status-filter behavior, though pagination and result ordering 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 tight sentences with zero waste: purpose and filter first, use cases next, return shape and sibling hand-off last. Nothing is buried or repeated.

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

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

With an output schema present, annotations covering safety, and full schema parameter coverage, the definition is nearly complete for a read-only list tool. The remaining gap is disambiguation from search_executions, which an agent could easily confuse when hunting a specific execution.

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 limit, statuses, and application all documented in the schema, so the baseline is 3. The description only restates that results can be filtered by status and are 'recent' (implying the limit), adding no syntax or semantic 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?

States a specific verb and resource with scope: 'List recent pipeline executions for a Spinnaker application, optionally filtered by status.' It distinguishes itself from get_execution explicitly, but does not clarify how it differs from the sibling search_executions, which appears to overlap on 'find a specific execution ID'.

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 use cases ('monitor deployment activity or find a specific execution ID') and names an explicit alternative: 'Use get_execution for full details of a specific run.' It fails to address search_executions, the sibling with the most overlapping intent, so the routing guidance is incomplete rather than exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so safety is covered. The description adds that results span all accounts and regions and come back grouped by account and region, which is meaningful behavioral context. It does not mention result size or pagination limits, which matters for an all-accounts enumeration.

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: scope first, then when to use, then return shape. No filler and no restatement of the title.

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?

Output schema exists, so return-value detail is mostly redundant, and the description still gives grouping behavior. The only gap is no warning about result volume or pagination when enumerating every account and region.

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?

There are zero parameters, so there is nothing to document; baseline applies. The description correctly implies the tool is unfiltered (it enumerates everything across accounts), which is the one semantic fact an agent needs.

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 verb and resource ('List all firewall rules (security groups)') plus explicit scope ('across all Spinnaker accounts and regions'). It also clarifies the domain vocabulary mapping (firewall = security group), which disambiguates from the singular get_firewall sibling.

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?

Names concrete use cases ('audit network security posture or find a specific security group') and explicitly routes the agent to the alternative tool ('before inspecting it with get_firewall'), making the list-vs-get split 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond those: the query spans all accounts and regions (i.e., no account/region filter is possible, expect a broad result) and the payload includes listener, health check, and attached server group 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 tight sentences, front-loaded with what the tool returns and its scope before the use case. The third sentence restates return contents that an output schema already covers, which is the only real 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?

With an output schema present and annotations covering read-only semantics, the description needn't document return values or safety. The one gap is operational: an all-accounts/all-regions listing could be large, and nothing is said about result volume or whether truncation occurs.

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

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

Only one parameter with 100% schema description coverage, so the schema already explains "application" as the Spinnaker-registered name. The description references the application scoping but adds no format, case-sensitivity, or wildcard guidance 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?

States a specific verb+resource ("List all load balancers") and scopes it to a Spinnaker application across all accounts and regions, which clearly separates it from single-object getters like get_cluster or get_application. It never names a sibling tool explicitly, so differentiation is inferred from the list/get split rather than stated.

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?

"Use this to inspect network routing and health check configuration for an application" gives a concrete use case that tells an agent when to reach for it. It stops short of exclusions — nothing says when to prefer list_server_groups or get_target_server_group instead, or what to do if the result is huge.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that results span all accounts and providers and mentions the returned fields, but it does not discuss pagination, result size, or latency across a broad open-world query, which is the main behavioral risk here.

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: purpose first, then use case, then return shape. The third sentence partially restates what the output schema already provides, but it is short enough that nothing feels padded.

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 read-only list tool with rich annotations and an output schema, this description covers purpose, scope, use case, and return contents. Nothing an agent needs in order to call it correctly 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering options exist and does not invent parameters that aren't 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?

States a specific verb and resource ('List all networks (VPCs)') plus the scope ('across all Spinnaker accounts and cloud providers'), which is enough to distinguish it from most siblings. It does not explicitly differentiate itself from nearby tools like list_subnets or list_firewalls, which an agent could plausibly confuse with network listing.

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?

'Use this to discover available networks when configuring deployment targets or security groups' gives a clear triggering context. There are no exclusions or named alternatives, so the agent must infer when list_subnets would be the better choice, but the positive guidance is solid.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds that the result is a JSON array of configuration objects containing name, stages, triggers, and parameters, which tells the agent what a pipeline record looks like. It does not address pagination or result-size limits, which is a minor remaining 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?

Three short sentences with zero waste: purpose, when to use, and return shape, in that order. Front-loaded with the verb and resource.

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

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

With full annotation coverage, a fully documented single parameter, and an output schema, the description needs only to explain intent and routing, which it does. The only missing element is any note on result volume or pagination for an open-world listing tool.

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

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

There is a single required parameter with 100% schema description coverage ('Application name as registered in Spinnaker'), so the schema carries the load. The description adds nothing about the application parameter's format or resolution beyond what the schema states — baseline 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?

States a specific verb and resource ('List all pipeline configurations') scoped to a Spinnaker application, and implicitly contrasts itself with the singular 'get_pipeline' by framing discovery 'before triggering or inspecting a specific one'. An agent can distinguish it from siblings 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?

Explicitly frames the use case as discovery before triggering or inspecting a specific pipeline, which effectively points at get_pipeline as the follow-up alternative. There is no explicit exclusion clause (e.g., when to use list_strategies vs list_pipelines), but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description's value-add is the return shape (array of server group objects with instance counts, provider, and region), but that largely duplicates the existing output schema, and it says nothing about pagination, empty results, or auth scope.

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 the core action and scope, with no filler. The final sentence restates return contents already captured by the output schema, which is mild redundancy but not harmful.

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

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

With rich annotations, a fully described single parameter, and an output schema, the definition covers what an agent needs to invoke it correctly. Remaining gaps (pagination, behavior on unknown application names) are minor for a simple read-only list.

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?

There is a single required parameter with 100% schema description coverage ("Application name as registered in Spinnaker"), so the schema carries the semantics. The description adds no format, casing, or lookup hints beyond what the schema provides — the correct baseline for fully covered 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?

States a specific verb and resource ("List all server groups") and adds disambiguating synonyms (ASGs, instance groups, replica sets) so the agent knows the underlying concept. It doesn't explicitly contrast with the sibling get_target_server_group, which retrieves a single group, so it falls short of full sibling differentiation.

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?

"Use this to view active deployment targets and their instance counts across regions and accounts" gives a clear condition for selecting this tool. There is no when-not guidance or explicit naming of alternatives such as get_cluster or get_target_server_group, so it is a 4 rather than 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile needs no restating. The description adds that the result is a JSON array of strategy configuration objects, but says nothing about permissions/authentication, behavior for an unknown application, or paging, so it adds only modest value.

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?

It uses three short sentences, and it front-loads the verb and resource ahead of the use case and return shape. Every sentence carries information, with no filler or repetition of schema fields.

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-parameter read tool with full annotation coverage and an output schema, the definition covers purpose, timing and return type. The only minor gap is behavior on a nonexistent or unauthorized application, which the description does not address.

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 single parameter has 100% schema description coverage ("Application name as registered in Spinnaker"), which already carries the semantics. The phrase "for a Spinnaker application" in the description only reinforces this and adds no format or example beyond the schema, so this is baseline territory.

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 definition opens with a specific verb and resource ("List all deployment strategy configurations") and scopes it to a Spinnaker application. It then gives concrete examples of what a strategy is (red/black, rolling, canary), so the agent knows exactly what comes back. No sibling in the list covers deployment strategies, so ambiguity is low.

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 states a clear use case: discover available strategies before saving or modifying one, which tells the agent where this fits in a read-then-write workflow. It does not name an alternative tool or state when not to use it, but no obvious alternative exists among the siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is covered. The description adds useful context by noting cross-account scope and the JSON array return shape with CIDR, AZ, and VPC fields, though it does not discuss pagination or limits.

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

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

Three tight sentences with no wasted language. Purpose is front-loaded, followed by usage context and return shape.

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-parameter read-only list tool with rich annotations and an output schema, the description supplies everything needed: scope, use case, and return contents. No material gaps remain.

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

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

The input schema has 100% description coverage and already documents cloud_provider with examples like aws, gce, and kubernetes. The description reinforces the parameter's role but adds no syntax or constraints 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?

States a specific verb and resource ('List all subnets') and scopes it to a cloud provider across Spinnaker accounts. An agent can distinguish it from sibling list tools such as list_networks or list_firewalls by the resource named.

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 clear usage context: 'Use this to discover available subnets when configuring server groups or deployment targets.' It does not explicitly name alternatives or exclusions, but the intended situation is 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered by structured data. The description adds real context beyond that: results are returned newest-first, as a JSON array, paged with a default size of 10. It stops short of anything else notable (e.g. total-count or whether filters are ANDed), so it is solid but not rich.

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 the sibling routing rule, then return/paging behavior. Nothing is repeated and nothing is wasted.

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 9-parameter read-only search with a fully described schema and an output schema present, the description covers what remains: purpose, sibling routing, ordering and paging default. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented with formats and examples, making 3 the baseline. The description only implicitly illustrates composition via the 'failed webhook run since yesterday' example, which hints at combining statuses, trigger_type and start_time but adds no syntax 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?

States a specific verb (search) and resource (pipeline executions) scoped to an application, and lists the filterable facets. It explicitly distinguishes itself from the sibling list_executions, so an agent can choose between them without opening either 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?

Explicitly says to use this instead of list_executions when executions must match specific criteria, and gives a concrete scenario ('every failed webhook run since yesterday'). The alternative and the selecting condition are both named rather than left to inference.

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