Output schemas not documented. Tool descriptions describe WHAT is returned as text (e.g., 'Returns app name, bundle ID, SKU') but no formal output schema is visible in the code. LLMs cannot reliably extract or chain results without knowing the exact response structure.
Many tool descriptions are under 100 chars and lack WHEN/WHY guidance. E.g., 'Get the beta app review submission status for a build' (52 chars) does not explain when to call it (after submit_build_for_beta_review?) or what to do with the response. LLMs struggle to contextualize when descriptions lack motivation.
Document output schemas for all tools. Use Zod or TypeScript interfaces to formally define response shapes, then transcribe them into tool descriptions or a schema registry. Example: 'Returns: { apps: Array<{id: string, name: string, bundleId: string, sku: string, primaryLocale: string}>, total: number }'
Expand tool descriptions to 100-200 chars and include WHEN/WHY context. Example: 'Get the beta app review submission status for a build. Call this after submit_build_for_beta_review to check if the build passed TestFlight review. Returns status: APPROVED, IN_REVIEW, REJECTED, or WAITING_FOR_REVIEW.'
Add error recovery guidance to tool descriptions. Example: 'If you see 'version not in PREPARE_FOR_SUBMISSION state', call get_app_versions first to check the current state. The version must be in PREPARE_FOR_SUBMISSION before associating a build.'
Implement confirmation step for delete_review_response. Require a confirmation_token parameter that is only obtained by calling a get_review_response_details tool that returns a token. Or add a confirm_delete=true parameter that must be explicitly set.
Add next_cursor or has_more flags to list tool responses. Instead of just returning the results, include pagination tokens so agents can fetch subsequent pages without recalculating offsets.
Standardize date/time format descriptions using formal JSON Schema patterns. Replace 'YYYY-MM-DD (daily), YYYYMMDD (weekly)' with pattern fields: format: 'date' for YYYY-MM-DD, or store the format rule in the parameter schema directly.
No error handling guidance. Tool handlers do not catch API errors and transform them into actionable recovery steps. For example, if 'set_build_for_version' fails because the version is not in PREPARE_FOR_SUBMISSION state, the LLM should be told 'The version must be in PREPARE_FOR_SUBMISSION state, call get_app_versions first to check the current state.' Current code does not include such hints.
Destructive tool 'delete_review_response' has no confirmation mechanism. Agents could irreversibly delete responses without a dry-run or confirmation step. The tool should either return a confirmation token that must be re-supplied, or decline to delete unless a confirmation parameter is explicitly set.
Tool chains incomplete, many tools return identifiers but downstream tools do not always accept the same identifier type. E.g., 'get_app' returns an app ID, and subsequent tools accept app_id. This works, but intermediate tools (e.g., analytics tools) return 'report_request_id' which is only consumed by 'list_analytics_reports'. Chains are not as fluid as they could be, no tool returns a report_id that feeds into a direct report getter.
Some parameter descriptions reference external context (e.g., 'report_date in format YYYY-MM-DD (daily), YYYYMMDD (weekly uses Sunday date), YYYY-MM (monthly)') but do not provide a formal regex pattern or JSON Schema format constraint. LLMs can misinterpret these rules, especially when formats differ by frequency.
Pagination limits are set per-tool but no consistency enforcement is visible. Some tools default to limit=50, others to limit=200. No tool explicitly states 'max 50 results enforced' or explains why the cap exists. LLMs may expect pagination info not provided in responses (e.g., next_cursor, total_count).
Create a 'get_analytics_report' tool that accepts a report_id and returns the report data directly, rather than forcing users to list reports and then infer which one to fetch. This simplifies the common case and reduces multi-step planning overhead.
Document parameter relationships explicitly in descriptions where one param's validity depends on another. Example: 'report_date format depends on frequency: use YYYY-MM-DD for DAILY, YYYYMMDD for WEEKLY (Sunday date), YYYY-MM for MONTHLY.'
Add per-tool security risk annotations. Tools like respond_to_review and update_version_localization modify public-facing content, clarify in descriptions that these are visible to end users and should be reviewed carefully.
Provide example successful responses in tool docstrings (not in descriptions, but in code comments or separate schema docs). LLMs benefit from seeing the exact structure they should expect, especially for complex nested responses.