connect_data

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

The annotations only indicate readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds valuable behavioral detail beyond that: persistence under the active API key's organization, that live sources are dialed during the call, that no separate per-route rate limit applies, and the exact status/return behavior (dataset_id/connection_id vs needs_selection with choices). This fully covers the side-effect profile of a mutation/onboarding 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?

The description is long but information-dense and logically structured: purpose, flow, side effects, return behavior, and alternative selection. It front-loads the core purpose and ends with clear routing. Slight redundancy exists between 'Use this instead of advanced connector/source tools' and the later 'Which to use' sentence, but every sentence earns its place given the tool's 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?

For a tool with 16 parameters, nested connector objects, a two-step selection flow, and no output schema, the description is remarkably complete. It explains both success and needs_selection return shapes, persistence semantics, rate limiting, legacy-vs-canonical parameter usage, and explicitly contrasts against sibling tools. An agent has enough context to invoke it 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 coverage is 94%, so the baseline is 3, but the description adds meaningful parameter context: connection_id is for resuming after selection, selection should use the choices object returned in the legacy flow, and legacy fields like provider/connection_type/connection_config are explicitly deprecated in favor of the connector envelope. This helps the agent choose among the many optional parameters.

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 opens with a specific verb and resource: 'High-level data onboarding flow' and states the outcome: 'Connect data once, pick the table/file/endpoint, and get a reusable dataset_id.' It explicitly distinguishes itself from 'advanced connector/source tools' and names sibling alternatives, so an agent can clearly tell it apart from onboard_dataset and register_source.

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 explicit routing guidance: 'Use this instead of advanced connector/source tools for normal users' and later says 'use onboard_dataset for inline data with semantic training, or register_source for advanced profiling and join detection.' It also describes the two-step flow for needs_selection, telling the agent exactly when to call connect_data again with connection_id.

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