No output schemas documented for any tool. LLMs cannot determine what fields are returned (e.g., does list-checks return 'checkId' or 'id'? Is count included? What about pagination cursors?). This breaks tool chaining, agents cannot confidently pass outputs from one tool to another.
No error handling guidance in tool descriptions. When a tool fails (e.g., 'Enterprise Support plan required' or 'Operation only available in us-east-1'), the LLM has no recovery path. Descriptions should include 'If this fails with X error, try Y' patterns.
list-trusted-advisor-checks
Recommendations
Document the output schema for every tool. For list-* tools: specify the response field name (e.g., 'recommendations': [{...}]), pagination structure (nextToken format, total count if available), and key fields returned (e.g., checkId, status, lifecycleStage). For get-* and update-* tools: document the full object structure returned.
Add error recovery guidance to descriptions. E.g., 'If you receive an error about Enterprise Support requirements, the calling account must upgrade. If the error is about us-east-1 only, you cannot use this operation in other regions.' This helps LLMs know when to retry vs. when to escalate.
Clarify the awsAccountId parameter. Add text like: 'Optional AWS Account ID. If provided, metadata is scoped to this account. If omitted, defaults to the credential account. Use this for cross-account operations if your credentials have cross-account IAM permissions.'
For list-* tools, document pagination behavior explicitly: 'Returns up to [maxResults] items. If more results exist, nextToken is included. Pass this token to the next call to fetch the next page. Maximum page size is 200.'
Add a note in tool descriptions about Support plan requirements: 'Requires Business, Enterprise On-Ramp, or Enterprise Support plan. Calls with Standard/Developer Support plans will fail with an authorization error.'
Consider adding per-resource success/failure details in batch-update-recommendation-resource-exclusion description. Clarify whether a partial failure returns per-item status or a blanket error.
Pagination parameters (maxResults, nextToken) present but no documentation on result structure. LLMs won't know whether to expect 'nextToken' vs 'cursor' vs 'page' in responses, or whether results are in 'items', 'recommendations', 'resources', or 'data' field.
awsAccountId parameter marked 'optional' but its role is unclear. Is it for cross-account access? Is it required in certain scenarios? Description should clarify when it's necessary and what happens if omitted.
Region parameter defaults to 'us-east-1' but descriptions state 'only available in us-east-1'. If an LLM passes a different region, the call will fail. Descriptions should be more explicit: 'This operation ONLY works in us-east-1. Passing any other region will result in a service error.' Alternatively, consider enforcing region server-side.
Document the lifecycleStage enum transitions. Are all transitions valid? Can you move from 'resolved' back to 'pending_response'? Can you dismiss an 'in_progress' recommendation? Implicit constraints invite LLM misuse.
For updateReasonCode enum, add brief descriptions of when to use each code (e.g., 'non_critical_account: for test or sandbox accounts' vs 'temporary_account: for resources being decommissioned').