list_aws_hosting_targets

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context beyond that: it instructs to 'render the response; do not derive or repair it', explains how to handle null managed values, requires surfacing every notice verbatim, and explicitly warns never to invent an account id or send infrastructureOwnership. This is rich, non-obvious behavior that an agent would not infer from the schema or annotations alone.

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

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

The description is longer than average but well-structured: it opens with the core usage scenario, then uses a bullet list to explain response fields, and finally provides decision logic and integration guidance. Every sentence adds value—there is no fluff. It could be slightly more concise by merging the parameter explanation with the schema, but it is efficient given the complexity.

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 that an output schema exists (though not shown), the description adequately explains the key output fields (managed, customerOptions, notices, selectedValue) and how to handle them. It also covers the decision logic and the exact value to pass to create_deployment. It does not mention pagination or error handling, but for a tool that returns a list of options, this is not a critical omission. It is complete enough for correct usage.

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%: the stackId parameter is already documented in the schema as 'Optional stack ID. Supply it before create_deployment so managed, notices, and selectedValue reflect that stack's AWS hosting rules.' The description repeats this same reasoning without adding new semantic details (e.g., format, constraints, or examples). Since the schema already covers the parameter fully, 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?

The description clearly states the tool's purpose: to choose which AWS account will own a deployment for a stack with deploymentTarget AWS_STATIC. It specifies the exact condition and the action to take, and it distinguishes itself from the sibling list_cloudflare_hosting_targets by referencing AWS specifically. It also ties to create_deployment, making its role in the workflow unambiguous.

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

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

The description provides explicit when-to-use guidance ('when an existing stack's deploymentTarget is AWS_STATIC'), and it explains the sequencing ('before create_deployment'). It also gives detailed decision rules: use it automatically if one option, let user decide if several, and do not create a deployment if none. It even instructs how to pass the returned value to create_deployment, leaving no ambiguity.

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