Document AgentKit tool response shapes

[saif-at-scalekit]

Problem

Developers calling AgentKit tools with execute_tool can see successful raw responses but still parse empty results because the SDK response wrapper is not documented clearly. The tool payload lives under response.data; tool-specific keys such as events and next_page_token are inside that payload.

A reported Google Calendar integration called googlecalendar_list_events and saw raw event data, but parsed zero events because it treated the response as a flat object instead of reading response.data["events"].

Desired docs improvement

Add generated response-shape documentation for connector tools so every tool documents:

• that the SDK wrapper returns the tool payload under response.data
• the top-level keys inside response.data
• expected value types where available
• short extraction examples for common list/pagination fields

Example:

response = client.actions.execute_tool(tool_name="googlecalendar_list_events", ...)

events = response.data.get("events", [])
next_page_token = response.data.get("next_page_token", "")

Implementation notes

The current generated connector data appears to store input params only. Check whether the tools API exposes an output or response schema. If it does, extend scripts/sync-agent-connectors.js, src/types/agent-connectors.ts, and src/components/ToolList.astro to render it from source-of-truth metadata. If not, add response schemas to the upstream connector registry first, then generate this documentation from that metadata.

Related immediate docs fix

The quickstart should also state that execute_tool payloads are read from response.data, and the Google Calendar examples should show response.data.get("events", []) for the reported failure mode.

[saif-at-scalekit]

SK-299 has been raised as a feature request for documenting tool response shapes from the upstream API. Once response schemas are available in the connector metadata, the sync script and docs generation can be extended to cover this.