spinnaker-mcp

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

Annotations already declare destructiveHint=false, idempotentHint=false, and openWorldHint=true, but the description adds genuinely useful behavior: cancellation does not roll back completed stages, and a confirmation message is returned. These effects go beyond the annotation set and materially affect how an agent uses the tool. It stops short of covering permissions or what happens to queued stages.

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, then the use case, then the critical caveat and return value. No sentence is wasted, and the important non-rollback limitation is stated plainly.

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 mutation tool with no output schema, the description supplies the return value and the key side-effect caveat, and annotations cover the safety profile. Slightly incomplete in that it says nothing about the non-idempotent behavior the annotations flag or what happens to not-yet-started stages.

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 (execution_id, reason) are already fully documented in the schema. The description's 'by its ID, optionally providing a reason' merely restates that, adding no format or syntax detail. 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 (cancel) and resource (running pipeline execution) with the scoping constraint 'by its ID'. It is clearly distinct from read siblings like get_execution/list_executions, but it never explicitly distinguishes itself from pause_execution, the closest sibling, leaving the agent to infer the difference.

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

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

Gives concrete when-to-use guidance: 'Use this to stop a deployment in progress — for example, when a bad build was triggered.' That is clear context, but there is no when-not guidance or reference to alternatives such as pause_execution or restart_stage.

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 destructiveHint=true and idempotentHint=false, so the safety profile is known; the description still adds real value with 'cannot be undone' and the non-obvious 'Does not affect past executions.' It omits what happens on a nonexistent pipeline name (error vs. silent no-op), which matters for a non-idempotent delete.

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 are front-loaded with the irreversible action and its consequences, with no filler or repetition. Every sentence contributes either scope, caution, or return behavior.

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 output schema, the description usefully states it 'Returns a confirmation message on success,' and the annotations cover the safety profile. For a destructive, non-idempotent operation it could still specify failure behavior on an unknown pipeline, so it is strong but not fully complete.

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

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

Schema description coverage is 100% and both required parameters (application, pipeline_name) are documented in-schema. The description adds no extra meaning such as name-vs-ID format or whether the application must already exist, so the baseline of 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 ('Permanently delete a pipeline configuration from Spinnaker'), which cleanly separates it from the many get_/list_ siblings and from save_pipeline/update_pipeline. The adverb 'permanently' also signals how it differs from a soft/disable-style operation.

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 when-to-use condition: 'Use this only when a pipeline is no longer needed.' It stops short of naming an alternative for reversible cases (e.g., updating or deactivating a pipeline via update_pipeline), so the routing guidance is clear but not complete.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the description's job is to add context rather than establish the safety profile. It adds the permanence warning ("cannot be undone") and describes the success result ("confirmation message"), useful return information not present in structured fields. It omits behavior for non-existent strategies or error cases, but that is a minor gap.

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

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

Two short sentences with zero filler; the destructive scope is front-loaded before the usage caveat and the return note. 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?

With annotations covering the safety profile, a fully documented two-parameter schema, and no output schema, the description covers the essentials including the success return. It does not address failure modes (e.g., deleting a non-existent strategy) or the non-idempotent implications of the annotations, leaving a small gap.

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 both parameters (application, strategy_name) are already documented in the schema, so the baseline is 3. The description adds no format, naming, or validation detail beyond what the schema provides.

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 ("permanently delete a deployment strategy configuration") and names the system (Spinnaker), so an agent can distinguish it from delete_pipeline or list_strategies. It does not explicitly contrast itself with sibling delete/save operations, which keeps it 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?

Gives a clear usage condition ("only when a strategy is no longer needed") and reinforces the irreversibility, which signals caution. It does not name an alternative tool (e.g., list_strategies to resolve a name, or save_strategy to modify instead of delete), so exclusions and alternatives are absent.

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 the safe read profile (readOnly, idempotent, non-destructive), and the description adds material context beyond them: reflection and class instantiation are blocked for security, and the result is returned as JSON. This is genuinely useful behavioral disclosure for a remote-evaluation tool.

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

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

Three tight sentences, front-loaded with the core purpose followed by usage, constraints, and return format. 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?

For a two-parameter read tool with full schema coverage and no output schema, the description covers purpose, usage, safety constraints, and return format. Nearly complete, though it could note any evaluation limits or error 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 description coverage is 100%, so the schema already documents both 'expression' and 'execution_id'. The description adds no further syntax or format guidance beyond the schema, 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 (Evaluate) and resource (SpEL expression against a pipeline execution context), with clear scope. No sibling tool performs expression evaluation, so the agent can distinguish it immediately.

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 inspect pipeline variables, stage outputs, or computed values during debugging, which gives a clear usage scenario. It does not name an alternative, but no sibling overlaps, so the omission is minor.

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 value beyond them by disclosing the return shape ('Returns JSON array of matching image objects'), which matters because no output schema exists; it says nothing about pagination or result limits, so it stops 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?

Three sentences that are front-loaded with purpose, then usage, then return value; each sentence carries information. It is slightly padded by the parenthetical provider examples and the restatement of filters, but there is no filler or 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?

For a read-only search tool with full schema coverage, the description covers purpose, use cases, filters, and return shape, and the annotations cover safety. With no output schema it usefully describes the return as an array of image objects; only pagination/limits and the distinction from get_image_tags are 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 schema already documents all four filters. The description only restates them at a high level ('filtering by query string, region, and account') without adding format, syntax, or matching-behavior detail, which is the baseline 3 case.

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 ('Search for machine images (AMIs, GCE images, Docker images)') scoped to Spinnaker and a cloud provider, which is far more precise than a bare 'find images'. It does not, however, distinguish itself from the sibling get_image_tags, leaving the agent to infer the boundary between the two.

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 usage contexts: 'find images for a deployment or verify which image versions are available.' That tells the agent when this tool is relevant, but offers no exclusions and never names get_image_tags or another alternative as the better choice in a given situation.

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 by structured data. The description adds that the response is JSON with full account metadata, which is useful given there is no output schema, but says nothing about auth requirements or error behavior for a missing account.

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 it does before the usage hint. The closing sentence about the return format earns its place because no output schema exists, though it is the thinnest of the three.

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 a fully described schema and covering annotations, the description is complete enough to call correctly. The absence of an output schema is partly offset by the note about returned JSON metadata, though no field-level detail is given.

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 the single 'account' parameter is documented as a Spinnaker account name. The description's 'by name' phrasing reinforces that this is a lookup key, but adds no format or constraint detail beyond the schema, 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 (Get) and resource (Spinnaker account) plus the key fields returned (cloud provider type, permissions, regions). It is clear on its own, but it never distinguishes itself from the sibling list_accounts or get_application, so an agent must infer the singular-vs-plural split.

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 names the use case: verifying account configuration or checking permissions before deploying. That is a real decision context, but it gives no exclusions or alternative routing (e.g., 'use list_accounts to enumerate all accounts').

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 safety is covered. The description adds value beyond that by disclosing the shape of returned data (metadata, accounts, clusters) and framing the tool as a pre-mutation inspection step, but says nothing about error behavior for unknown applications.

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 what the tool does and why to call it. Slight redundancy: 'accounts, clusters' appear in sentence one and again in the return-value sentence, which trims it below a perfect score.

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 output schema, the description usefully compensates by summarizing the return payload, and all required parameters are covered. It is nearly complete for a simple read tool, missing only edge-case behavior such as a not-found application.

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 the single parameter 'application' is fully documented in the schema as the registered application name. The description adds no format, casing, or lookup nuance beyond what the schema states, 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 detailed information about a single Spinnaker application') and enumerates the payload scope (accounts, clusters, custom attributes). The word 'single' cleanly separates it from the sibling list_applications, so an agent can route without opening schemas.

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 use context: inspect configuration before modifying pipelines or infrastructure. It does not name the alternative (list_applications) or state when not to use it, 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('JSON with cluster metadata and its constituent server groups'), which is not captured in any structured field.

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 identifiers before the use case and return note. There is minor redundancy in mentioning 'server groups' both as an inspection target and as returned content, but no 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?

With no output schema, the description compensates by describing the returned JSON contents, and all three parameters are fully documented. The remaining gap is sibling differentiation from list_clusters, but nothing needed to invoke the tool 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 description coverage is 100%, so the schema fully documents application, account, and cluster_name; the baseline is 3. The description restates 'by account and cluster name' but adds no syntax, format, or validation detail beyond what the schema provides.

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 gives a specific verb and resource ('Get details for a specific cluster in a Spinnaker application') and names the three required identifiers, making the tool's scope unambiguous. It does not explicitly contrast itself with the sibling list_clusters, so the singular-vs-list distinction is only implied.

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 an implied use case. However, it never states when NOT to use it or directs the agent to alternatives such as list_clusters or get_target_server_group, leaving routing 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, and destructiveHint=false, so safety is covered. The description adds that it returns 'raw console output text', which is useful for understanding output format. No further behavioral traits like rate limits or auth requirements are mentioned, but the return format disclosure is valuable.

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

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

Three sentences, each earning its place: purpose, usage, and return value. Front-loaded with the action. No wasted words.

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

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

Given annotations cover safety, schema covers parameters fully, and there is no output schema, the description is largely complete. It states the return type ('raw console output text') which compensates for the missing output schema. It could mention that the provider parameter is optional, but that is a minor gap.

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 schema already documents all four parameters thoroughly (region, account, provider, instance_id). The description mentions 'Requires account, region, and instance ID', which aligns with required parameters but adds no semantic detail beyond the schema. 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 ('Get the console output (boot log) for a specific compute instance'), clearly differentiating from siblings like get_instance or get_execution. The parenthetical 'boot log' adds precision about what console output means here.

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 when to use it: 'debug instance startup failures or inspect early boot messages.' This gives clear context. It does not name an alternative tool or state when not to use it, keeping it below 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds real value beyond them by describing the payload shape ('comprehensive JSON with per-stage results') and the scope of data returned. It does not mention pagination or size limits, but for an ID-scoped read those are minor.

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, all load-bearing: what it returns, why to call it, and where the ID comes from. The purpose is front-loaded and nothing is repeated from the name or annotations.

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 tool with no output schema, the description adequately compensates by summarizing the return contents and the sourcing of the ID. A note on result size or error behavior (e.g. not-found handling) would make it fully self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns extra by naming three provenance sources for execution_id (trigger_pipeline, list_executions, search_executions), one more than the schema itself lists. It adds no format details beyond the schema's UUID note.

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 full details of a single pipeline execution by its ID') and enumerates the returned content (stage statuses, outputs, variables, timing). This clearly distinguishes it from sibling list_executions/search_executions, which return many executions rather than one.

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 use cases ('debug a failed deployment or inspect execution progress') and tells the agent where the required ID comes from (trigger_pipeline, list_executions, search_executions). It stops short of an explicit when-not rule, but the single-vs-list split is implied well enough to route correctly.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint). The description adds that it returns the full rule set and metadata, which is useful, but it does not disclose error behavior (e.g., what happens for a nonexistent rule) or auth/permission requirements that would go beyond the 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?

Two sentences, front-loaded with the identifying key and resource, then the inspection use case and return content. 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?

For a 3-param read-only lookup with 100% schema coverage and no output schema, the description is nearly complete: it identifies the key, the use case, and the return shape. It stops short of mentioning pagination or error handling, but those are minor for a single-resource get.

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 three parameters (name, region, account) are already documented in the schema with examples like 'us-east-1' and 'Spinnaker account name'. The description only restates the requirement to supply account, region, and name, adding no new semantics such as format constraints or optionality. 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 (Get), resource (firewall rule / security group), and the composite key (account, region, name). It explicitly distinguishes itself from its obvious sibling list_firewalls by being the single-item lookup rather than the collection.

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 use case ('inspect inbound/outbound rules and associated resources'), which tells the agent this is the inspection tool. However, it does not explicitly name list_firewalls as the alternative for enumeration, so routing guidance is implied rather than stated.

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 is covered. The description adds the return format (JSON array of tag strings), which is useful, but no rate limits, auth requirements, or pagination behavior are 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 short sentences, each earning its place: purpose, usage, return shape, in that order. 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?

For a 2-parameter read-only tool with no output schema, the description covers purpose, usage context, and return format. Nothing critical for correct invocation is missing, though sibling routing is 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 description coverage is 100% and both parameters (account, repository) are documented with an example in the schema. The description adds no syntax or format detail beyond the schema, 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 (get), resource (image tags), and scope (Docker image repository registered in Spinnaker). This is distinguishable from find_images, which searches rather than enumerates tags, though the description never names a 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?

Gives clear context: 'Use this to list version tags before triggering a pipeline with a specific image tag.' This tells the agent when the tool is relevant, but offers no exclusions or named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds only a brief return note ('Returns JSON with full instance details including health indicators') with no detail on error behavior, permissions, or response shape beyond that; with no output schema this is useful but thin.

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, both front-loaded with the core action and then the use case/return, with no filler or repetition beyond a minor overlap between 'metadata' and 'full instance details.'

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

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

With no output schema, the description does supply a brief statement of what is returned, and annotations cover the safety profile, so an agent has enough to call it. It remains slightly incomplete on return structure and failure modes, but 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% and all three parameters are documented in the schema (region, account, instance_id with examples). The description only restates the identifying keys without adding format or constraint meaning, 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?

The description states a specific verb and resource ('Get details for a specific compute instance') and names the three identifying keys, making it clearly distinct from resource-oriented siblings like get_cluster or get_account. It stops short of explicitly naming an alternative sibling tool, so it does not reach the top of the scale.

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 clear, concrete use context. However, it offers no when-not-to-use guidance and does not point to any alternative tool for related lookups.

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 value by disclosing what is returned ('complete pipeline JSON definition including all stage configurations'), though it says nothing about auth requirements or behavior for a nonexistent pipeline.

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 compact sentences, front-loaded with the core action, then usage, then return shape. No filler, though the third sentence partly overlaps with the first's 'full configuration'.

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

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

No output schema exists, so the description usefully covers the return shape (pipeline JSON with stage configs). Combined with rich annotations and 100% schema coverage, an agent has enough to invoke it correctly; only edge-case behavior (missing pipeline, permissions) 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% with both parameters documented ('as registered in Spinnaker', 'as shown in the Spinnaker UI'), so the schema does the heavy lifting. The description only restates the lookup keys and adds no format or disambiguation detail, matching the 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 ('Get the full configuration of a specific pipeline') and pins the lookup keys to application and pipeline name. It distinguishes itself from list_pipelines by scope ('a specific pipeline'), but never names the sibling it differs from, so differentiation is implied rather than explicit.

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 a clear use context: 'inspect pipeline stages, triggers, and parameters before triggering or modifying it.' That tells the agent when to reach for this tool, but there are no exclusions or named alternatives (e.g. get_pipeline_history, list_pipelines).

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 value beyond them by disclosing the return shape (JSON array of historical versions ordered by update time), which the annotations do not convey.

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 usage, then return format. Every sentence earns its place and the key information is front-loaded.

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

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

With no output schema, the description compensates by stating the return is a JSON array of versions ordered by update time, and annotations carry the safety profile. It omits any pagination behavior for the limit parameter, a minor gap given the schema already documents the default.

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 (pipeline_config_id and limit with its default of 10) are already fully documented. The description adds no syntax or behavioral detail about the parameters, 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+resource ('Get the version history of a pipeline configuration') and clarifies the scope as past revisions, which cleanly separates it from siblings like get_pipeline (current config) and update_pipeline (mutation). An agent can select it 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 names two use cases ('audit changes to a pipeline or compare previous configurations'), giving clear context for invocation. It does not, however, name alternatives or state when not to use it (e.g., use get_pipeline for the current revision), 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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description usefully adds the return shape (JSON array of records with timestamps, descriptions, status), which is not derivable from the 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?

Three sentences, zero waste, front-loaded with the core purpose before usage and return details. Every sentence 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?

With no output schema, the description correctly compensates by summarizing the return payload, and annotations cover the read-only safety semantics. It is nearly complete, though it says nothing about pagination or result volume for what could be a large activity 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?

Schema description coverage is 100%, so all five parameters are already documented in the schema and the description adds no syntax, format, or constraint detail beyond it. 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 names a specific verb (Get) and resource (scaling activities) and scopes it to a server group within a Spinnaker cluster. No sibling tool overlaps with this resource, so the purpose is unambiguous, though it does not explicitly contrast itself with any alternative.

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 recent auto-scaling events (scale-up, scale-down) and diagnose capacity issues" gives clear intent-based guidance for when to reach for this tool. It lacks explicit exclusions or named alternatives, but the use case is well-defined.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds that the tool returns JSON with matched server group details, but discloses nothing else behavioral (no note on ambiguity resolution when multiple candidates match).

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, followed by usage and the return format. Tight with no filler, though the strategy enumeration slightly duplicates the schema's target description.

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 all parameters documented and no output schema, the description covers purpose, usage, and a brief return note. It is nearly complete, only missing clarification of ambiguous-match behavior when several groups satisfy the target strategy.

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 six parameters are already documented, making the 3 baseline appropriate. The description's strategy examples are helpful, but it introduces a mismatch: it lists 'fail' as a target while the schema documents 'ancestor', which could confuse an agent on valid values.

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 server group in a Spinnaker cluster), plus the distinguishing mechanism: a target selection strategy rather than a name. This separates it from list_server_groups, but it does not name that sibling explicitly, so an agent must infer the contrast.

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 a clear when-to-use condition: 'when you need the most recently deployed or a specific server group without knowing its exact name.' It gives no explicit when-not or named alternative, though the 'without knowing its exact name' framing implicitly routes named lookups elsewhere.

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 value beyond them by disclosing the return payload shape (status, start/end times, retry info, step-by-step execution details), which is meaningful since no output schema exists.

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, zero filler. The core purpose is front-loaded, the usage trigger follows, and the return summary comes last 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 single-parameter read tool with no output schema, the description covers purpose, usage context, and return contents. Nothing essential for correct invocation is missing, and the absence of an output schema is compensated by the inline return 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?

Schema description coverage is 100% and there is only one parameter, so the schema fully documents task_id including its provenance. The description adds no syntax, format, or lookup guidance beyond the schema, 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 the status and details of a Spinnaker orchestration task') and enumerates concrete task types (deploy, resize, rollback, delete). It does not explicitly distinguish itself from the closely-named sibling get_execution, so an agent must infer the task-vs-execution boundary.

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 a clear contextual trigger: 'Use this to monitor the progress of a long-running infrastructure operation.' However, it names no alternative tool and gives no when-not-to-use conditions (e.g., when get_execution is the better pick).

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 and idempotency profile is fully covered by structured data. The description adds return-shape context ('JSON array of account objects with provider type, environment, and permissions') and the prerequisite role, which is useful but doesn't reveal pagination, size limits, or auth requirements.

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, when-to-use, and return contents. Front-loaded with the verb and resource, no 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 zero-param read-only list tool with annotations covering the behavioral profile and no output schema, the description is nearly complete: it states purpose, usage trigger, and return fields. Only minor gaps remain (e.g., whether pagination occurs, or whether results are cached).

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 a parameterless enumeration by saying 'List all configured' with no filters mentioned.

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 parenthetically clarifies what an account is ('cloud provider integrations'). This clearly distinguishes it from the singular sibling get_account and from other list_* tools targeting 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?

Provides clear usage context: 'Use this to discover available cloud accounts before querying infrastructure or deploying.' This tells the agent when to reach for it. It doesn't explicitly name get_account as the alternative for a single account, so not a full 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. The description adds genuinely useful non-structured context — that it returns a JSON array of application objects with name, email, accounts, and cloud providers — which matters because no output schema exists. It omits any note on pagination or volume, keeping it from 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?

Three sentences, each earning its place: purpose, workflow role, and return shape. The most important information (it lists all applications) is front-loaded with zero 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 zero-parameter read tool with annotations covering safety and no output schema, the description covers what it does, when to use it, and what comes back. The only minor gap is absence of any note about result volume or ordering for a potentially large listing.

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 per the rubric the baseline is 4. There are no arguments whose semantics need explaining, and the description invents none.

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+resource ("List all Spinnaker applications with their metadata") and clarifies scope as a full listing, which distinguishes it from the singular sibling get_application. An agent can tell immediately what this 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?

"Use this as a starting point to discover available applications before querying pipelines or infrastructure" gives clear context for when to reach for this tool in a workflow. It stops short of naming explicit alternatives (e.g., get_application for a single app), so it is clear but not fully 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the grouping by account and the JSON-shape return (account names to arrays of cluster names), which matters because there is no output 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 tight sentences with no waste: purpose and scope first, usage routing second, return shape last. Every sentence earns its place and the key constraint is front-loaded.

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

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

For a one-parameter read tool, the definition is complete: annotations cover safety/idempotency, the description covers grouping and return shape in lieu of an output schema, and the routing to get_cluster is stated. Nothing an agent needs 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?

Schema description coverage is 100% for the single 'application' parameter, so the schema already carries the semantics. The description confirms the application-scoping but adds no format or syntax detail beyond what the schema provides; 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 (list), resource (cluster names), and scope (for a Spinnaker application, grouped by account), and explicitly distinguishes itself from the sibling get_cluster. An agent can tell it apart from get_cluster and list_server_groups without opening a 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?

Names the alternative explicitly (get_cluster) and the sequencing condition (discover clusters first, then drill into a specific one). Clear context, though it never states a when-not or any exclusion, so it falls short of the full 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context the annotations don't: the return shape (JSON array of execution summaries with status, timing, trigger info) and the recent-executions scope, which implies truncation 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 tight sentences, front-loaded with the core action, then usage, then return format and the sibling hand-off. No filler or 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 no output schema, the description compensates by describing the returned array contents, and it covers scope, filtering, and the alternative tool. Nothing needed to call this 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 description coverage is 100% — limit, statuses, and application are all documented in the schema with defaults and examples. The description only restates the status filter and adds no syntax or format detail beyond it, 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 (List) and resource (pipeline executions) scoped to a Spinnaker application, plus the optional status filter. An agent can distinguish it from get_execution and the other list_* 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?

Gives concrete use cases (monitor deployment activity, find an execution ID) and explicitly routes to get_execution for full details of a single run. It does not mention the sibling search_executions, which is a near-neighbor an agent might confuse it with, 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 readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds meaningful context beyond that: the operation is unfiltered across all accounts and regions, and the return shape is a JSON array grouped by account and region, which matters since no output schema exists.

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 scope and resource, then the use case, then the return format. No filler, and each sentence adds a distinct piece of 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 no-parameter, read-only list tool with no output schema, the description supplies the scope, the routing alternative, and the return format. Nothing an agent needs to select or 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?

Zero parameters, so per the rubric the baseline is 4. The description correctly communicates that no filtering parameters exist ('across all Spinnaker accounts and regions'), which is a useful negative-space signal rather than a gap.

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 (List) and resource (firewall rules / security groups), clarifies the alias between the two terms, and gives the full scope ('across all Spinnaker accounts and regions'). This distinguishes it cleanly from the sibling get_firewall, which fetches a single group.

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 names two use cases (auditing network security posture, and locating a specific security group before inspection) and routes the agent to the sibling get_firewall for the follow-up. Lacks an explicit when-not statement, but the alternative is named, so it is well above implied usage.

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, open-world, non-destructive semantics, so the safety profile is covered. The description adds genuine value beyond that: the cross-account/region scope and the shape of returned objects (listener, health check, attached server group details). It omits pagination/rate-limit behavior, keeping it below 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?

Three sentences, zero waste, and front-loaded: scope first, use case second, return contents third. Each sentence carries distinct 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?

With no output schema, the description carries the return-value burden and does so ('JSON array of load balancer objects with listener, health check, and attached server group details'). Annotations cover safety, the single parameter is documented in both schema and prose, leaving no meaningful gap for a read-only list 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 coverage is 100% for the single 'application' parameter, and the description only implies it via 'for a Spinnaker application' without adding format or constraint detail. Baseline 3 is the ceiling when the schema fully documents the parameter.

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

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

States a specific verb and resource ('List all load balancers') plus the scoping constraint ('for a Spinnaker application across all accounts and regions'). The resource is inherently distinct from all siblings (clusters, firewalls, networks, server groups), so an agent can identify it without ambiguity.

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

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

Provides a clear use case ('Use this to inspect network routing and health check configuration for an application'), giving the agent context for when to reach for it. It stops short of naming alternatives or when-not-to-use conditions, so it earns 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, and non-destructive, so safety is covered. The description still adds value by disclosing that results are unfiltered across all accounts and providers and by naming the returned fields (provider, account, CIDR), though it omits pagination or result-size 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 tight sentences: purpose and scope first, then when to use it, then return shape. No filler and everything is front-loaded.

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

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

For a zero-parameter read-only lister with no output schema, the description covers purpose, usage, and returned object shape, which is nearly everything an agent needs. Pagination or result-size limits are the only unaddressed detail.

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; there is no parameter semantics to document. The description implicitly confirms the no-filter design by saying it lists across all accounts and providers.

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 explicit scope ('across all Spinnaker accounts and cloud providers'), which separates it from sibling list tools like list_subnets and list_firewalls. An agent can identify it 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?

Gives clear usage context ('use this to discover available networks when configuring deployment targets or security groups'), which is a genuine when-to-use signal. It stops short of naming sibling alternatives or stating exclusions, so it is clear context but not 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 readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('JSON array of pipeline configuration objects with name, stages, triggers, and parameters'), which annotations cannot convey.

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, zero redundancy, and the core purpose is front-loaded before usage and return-value details. Every sentence carries distinct 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 single-parameter read-only list tool, the description covers purpose, usage context, and return contents, compensating for the absence of an output schema. Nothing an agent needs 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?

Only one parameter ('application') and schema coverage is 100%, so the schema fully documents it as 'Application name as registered in Spinnaker'. The description adds no syntax or format detail beyond the schema, which is the expected baseline at this coverage level.

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 ('List') and resource ('pipeline configurations') scoped to a Spinnaker application. The phrase 'before triggering or inspecting a specific one' implicitly distinguishes it from get_pipeline, so an agent can route correctly 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 explicit context: 'Use this to discover available pipelines before triggering or inspecting a specific one.' That frames the discovery step and points at the follow-up tool (get_pipeline / trigger_pipeline) without naming them outright, so it is clear but not a fully explicit when/when-not with named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds value beyond that by describing what comes back (instance counts, cloud provider details, region info) and confirming this is an unfiltered listing of all server groups for the app.

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, zero redundancy: purpose first, then usage, then return shape. Every clause carries information and the most important routing fact (what is listed and for whom) is front-loaded.

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

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

With no output schema, the description correctly carries the return contract (JSON array of server group objects with instance counts, provider and region info), which is what an agent needs. The remaining minor gap is that pagination/volume expectations and sibling routing are not mentioned, but for a simple one-argument read tool the coverage is largely adequate.

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 description coverage is 100%, so the schema already fully documents 'application' as the registered Spinnaker app name. The description adds a small reinforcing hint ('for a Spinnaker application') but no format, casing, or validation detail 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?

Starts with a specific verb+resource ('List all server groups') and immediately disambiguates the resource by naming cloud-specific equivalents (ASGs, instance groups, replica sets). The scoping phrase 'for a Spinnaker application' tells an agent exactly what universe the listing covers, distinguishing it from get_target_server_group and get_cluster.

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 view active deployment targets and their instance counts across regions and accounts' gives a concrete use case and the axes it spans. It stops short of naming alternatives or stating when NOT to use it (e.g., versus get_target_server_group for a single group), so no explicit routing is provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds the return shape (JSON array of strategy configuration objects), which matters because no output schema exists. It does not mention pagination or filtering limits, but for a discovery list this is solid added context.

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

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

Three sentences, front-loaded with the core action, then usage, then return format. Each sentence earns its place with 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 one-parameter read tool with no output schema, the description covers purpose, usage timing, examples, and return shape. Nothing an agent needs in order to select or 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 description coverage is 100% for the single 'application' parameter, so the schema already carries the semantics. The description only restates that results are for 'a Spinnaker application' and adds no format or naming detail beyond the schema, making the 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 (list) and resource (deployment strategy configurations) scoped to a Spinnaker application, and names concrete examples (red/black, rolling, canary). An agent can distinguish it from sibling tools like list_pipelines or delete_strategy 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 says when to use it: to discover available strategies before saving or modifying one, which implicitly routes the agent to save_strategy/delete_strategy afterward. It gives clear context but no explicit exclusions or named alternatives, 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 readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds useful context beyond that: the multi-account scope and the shape of the return (CIDR, AZ, VPC association). It omits pagination or result-size behavior, which keeps it from 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?

Three sentences, front-loaded with the action and scope, followed by the use case and the return contents. Every sentence carries information the agent needs; no 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 single-parameter read tool with no output schema, the description covers the action, scope, intended use, and return fields, and the annotations carry the safety profile. Only minor gaps remain (pagination/limits, account scoping details), which are not critical here.

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 fully documents cloud_provider with examples (aws, gce, kubernetes). The description's 'for a given cloud provider' merely restates the parameter without adding format or constraint detail, matching the baseline for full schema coverage.

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

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

The description gives a specific verb and resource ('List all subnets') plus scope ('for a given cloud provider across Spinnaker accounts'), so the agent knows exactly what comes back. It does not, however, distinguish itself from the closely related list_networks sibling, which an agent could easily confuse it with.

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 concrete use case: 'discover available subnets when configuring server groups or deployment targets.' That is a clear when-to-use signal, but it names no exclusions or alternatives (e.g., list_networks vs. list_subnets), leaving routing 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 it non-readOnly, non-idempotent, and non-destructive; the description adds meaningful detail beyond them: the pause takes effect at a stage boundary rather than immediately, and the action is reversible via resume_execution. It doesn't state authorization requirements or behavior when the execution isn't mid-pipeline.

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 the core action front-loaded and no redundancy. The closing return-value sentence is mildly useful given there is no output schema, though it is close to 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 one-parameter tool with annotations covering the safety profile, the description is nearly complete: it explains scope, reversibility, and the confirmation return. A minor gap is what happens if the execution is not currently running or already paused.

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 a single well-documented execution_id parameter, so the schema carries the load. The description adds no format or sourcing detail beyond what the schema provides; 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 ('Pause'), resource ('running pipeline execution'), and granularity ('at the current stage boundary'), which cleanly separates it from sibling tools like cancel_execution, resume_execution, and restart_stage.

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 a concrete use case (temporarily halt a deployment for manual review) and points to the follow-up tool, resume_execution. It does not contrast against cancel_execution, so the agent must infer when pausing is preferable to cancelling.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds that the call returns a confirmation message, but it does not warn that the operation is non-idempotent, meaning repeated restarts could produce duplicate executions.

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 action front-loaded, followed by the use case and the required inputs. No filler or redundant restatement.

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 output schema, the description appropriately notes the confirmation-message return and lists required inputs, so an agent has enough to invoke it. It omits the significant caveat that the operation is non-idempotent and what happens if the stage is already running, which would complete the picture for a mutation 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% for both parameters, so the schema already documents execution_id and stage_id. The description only restates that these IDs are required, adding no format, constraint, or state-precondition 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 ('Restart a specific failed or completed stage within a pipeline execution') and scopes it clearly against re-running the whole pipeline. An agent can distinguish this from siblings like trigger_pipeline or resume_execution without opening a 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 a concrete when-to-use condition ('retry a stage that failed due to a transient error') and implicitly rules out full-pipeline re-runs. It does not explicitly state when not to use it (e.g., a stage that failed for a non-transient reason) or name the nearest 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=false, destructiveHint=false, and idempotentHint=false, so the mutation/non-idempotent profile is covered. The description adds the continuation semantics and notes a confirmation message is returned (useful with no output schema), but says nothing about failure when the execution is not paused or permission requirements, so it is adequate rather than 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 short sentences, front-loaded with the core action and no filler. Every sentence adds a distinct piece of information: what it does, when to use it, and what it returns.

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 mutation with annotations covering the safety profile, the description supplies purpose, prerequisite, and return behavior. Without an output schema and without stating error/edge-case conditions, it is nearly but not fully complete.

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

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

Only one parameter (execution_id) with 100% schema description coverage, so the schema fully documents it and the description adds no format or source guidance. Baseline 3 is appropriate when structured data carries the parameter semantics.

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

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

States a specific verb (resume) and resource (paused pipeline execution) plus the scope qualifier 'continuing from where it was halted,' which distinguishes it from restart_stage, trigger_pipeline, and get_execution. An agent can identify the operation 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 says to use it 'after pause_execution once the manual review or intervention is complete,' naming the counterpart tool and the triggering condition. It does not address when-not to use it (e.g., a canceled or already-running execution) or other alternatives like cancel_execution.

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=false, destructiveHint=false, and openWorldHint=true, so the mutation profile is partly covered. The description adds value beyond that: it calls out that this is a mutating operation, that the new pipeline becomes visible in the Spinnaker UI, and that it returns a confirmation — effects an agent can't infer from the annotations alone. It omits any auth/permission requirements or failure modes, but the added context is meaningful.

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 immediately followed by the sibling routing rule, which is the most decision-relevant information. The third sentence slightly repeats the creation fact already established, costing a little efficiency.

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 create tool with no output schema, the description covers purpose, the alternative to use for updates, the mutating nature, the UI visibility effect, and the confirmation return. Nothing essential for correct invocation 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?

With a single parameter at 100% schema description coverage, the schema already documents pipeline_json as the full pipeline JSON definition. The description restates that it accepts a full pipeline JSON definition but adds no format, size, or validation detail beyond the schema, so the baseline of 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 (save a new pipeline configuration to Spinnaker) and explicitly scopes it to brand-new pipelines, naming update_pipeline as the contrasting sibling. An agent can distinguish it from update_pipeline without inspecting 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 for creating a brand-new definition and to use update_pipeline instead for modifying an existing one. The when-to-use and when-not-to-use conditions are both spelled out with a named alternative.

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 the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds only 'returns a confirmation' and echoes the create-new semantics that align with idempotentHint=false; it says nothing about overwrite behavior if the strategy already exists or any permission requirements.

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?

Purpose is front-loaded in the first sentence, with the alternative and return behavior following. Three tight sentences, though the JSON-acceptance clause is slightly redundant given the schema.

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 create tool with annotations already carrying the safety profile and no output schema, the description covers purpose, the create/delete pairing, and the return confirmation. Adequate, with only minor gaps around idempotency/overwrite semantics.

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 single strategy_json parameter is already fully documented. The description's 'accepts a full strategy JSON definition' merely restates the schema field, adding no format, shape, or example beyond what structured data provides.

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 ('Save a new deployment strategy configuration to Spinnaker') and grounds it with concrete examples (red/black, rolling push, canary). It also names the contrasting sibling delete_strategy, so an agent can distinguish create from remove 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 frames the use case ('create a reusable deployment strategy') and routes the removal case to delete_strategy. It stops short of stating when NOT to use it or how it relates to list_strategies or save_pipeline, so it is clear but not 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that it returns a JSON array of matching execution summaries, which is useful given there is no output schema, but it says nothing about result caps, pagination, or auth requirements. Adequate 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, no filler, with the core purpose front-loaded and the sibling routing second. Every sentence contributes a distinct fact (what, when-to-use, what it returns).

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 output schema, the description steps in with a return-shape statement, and the six filters are fully documented in the schema. What is missing is any note on result limits or ordering, which matters for a search tool that can match many executions. Close to complete for this complexity level.

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 type and ISO 8601 / example values. The description only restates the filter categories (status, trigger type, time range) without adding syntax or edge-case semantics. 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?

States a specific verb (search) and resource (pipeline executions), plus the scoping dimension (across an application) and the filter axes it supports. It explicitly names the sibling it is not — list_executions — so an agent can route 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?

Contains an explicit 'use this instead of list_executions when...' clause with the selecting condition (finding executions matching specific criteria). This is exactly the when-to-use vs alternative guidance the dimension asks for.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true. The description reinforces this with 'mutating operation that starts a real pipeline run,' which flags that the call has real-world side effects, and it also names the return value (execution reference ID) in the absence of an output schema. It doesn't cover permissions, rate limits, or error behavior, so 4 rather than 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?

Four short sentences, front-loaded with what it does, then usage, then return value, then mutation warning. Every sentence contributes. The final 'mutating operation' sentence partly restates the annotations, which keeps it from a clean 5.

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 output schema, the description correctly fills the gap by explaining the return (execution reference ID and how to use it). Parameters are fully covered by the schema, and the mutating/complexity profile is disclosed. An agent has everything it needs to call this 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 application, pipeline_name, and the JSON parameters object are already documented by the schema. The description adds only 'optional parameters' without syntax or format detail beyond the schema's example. Baseline 3 is appropriate when the schema carries parameter meaning.

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?

Specific verb+resource: 'Trigger a new pipeline execution with optional parameters.' It clearly distinguishes itself from read-only siblings like get_pipeline and list_pipelines, and the domain (Spinnaker pipelines/deployments) is concrete enough that an agent can select it without opening a 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?

'Use this to start a deployment, build, or any configured pipeline workflow' gives clear activation contexts, and it points to get_execution/list_executions for monitoring. It lacks explicit when-not guidance (e.g. use cancel_execution to stop, or don't trigger for read-only inspection), so it stops 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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description adds genuinely new context: the operation overwrites the current config (full replacement, not a merge) and returns a confirmation. There is mild tension with idempotentHint=false, since a full-JSON overwrite behaves idempotently, but the description itself asserts nothing contradictory.

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 verb and resource, then the alternative, then behavior. Every sentence carries information, though the closing 'mutating operation' clause partially restates the readOnlyHint=false annotation.

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 mutation with no output schema, the description covers what changes, what it replaces, how it differs from save_pipeline, and that a confirmation is returned. Only minor detail (failure/permission behavior) is absent, which is acceptable given the annotation coverage.

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 both parameters are self-documented and the baseline would be 3. The description earns above baseline by clarifying that pipeline_json is a *full* pipeline definition (replacement semantics rather than a partial patch), which the schema does not convey.

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 ('Update an existing pipeline configuration in Spinnaker') and explicitly distinguishes itself from the sibling save_pipeline. An agent can select 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?

Gives an explicit condition ('a pipeline that already exists') and names the alternative with its own condition ('use save_pipeline instead to create a new one'). It also enumerates the modifiable aspects (stages, triggers, parameters), so when-to-use is unambiguous.

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