connection_schema_config

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

With no annotations, the description carries full burden. It discloses important behaviors: omits unedited columns, does not apply to Magic Folder connectors, specific behavior for NetSuite/Salesforce connectors, and schema file confirmation requirement. It does not explicitly state idempotency or rate limits, but the read-only nature is implied. The warning about parent schema adds transparency.

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 relatively long but well-structured. It front-loads a critical warning, then defines purpose, usage notes, alternative endpoints, and special cases. Every section adds distinct value, though some links and notes could be condensed. The structure is clear and effective.

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 the tool's complexity and lack of output schema, the description covers all necessary information: what is returned (global flags, schemas, tables, overridden columns), what is not returned (unedited columns), alternative endpoints for different needs, connector-specific behaviors, and explicit exclusions (Magic Folder). It also includes a prerequisite warning. The two parameters are fully explained.

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 100% with both parameters described. The description adds value beyond the schema by instructing users to first read a schema file and provide the exact path for the 'schema_file' parameter, which is not in the schema description. The 'connection_id' parameter is straightforward. Overall, the description enhances understanding of one parameter significantly.

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 this tool returns the top-level schema configuration for an existing connection. It distinguishes itself from sibling tools like modify_connection_schema_config (write) and connection_column_config (exhaustive column list) by specifying its read-only nature and the scope of data (global flags, schemas, tables, overridden columns only).

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 guidance on when to use this tool (read current config, backup, copy) and when to use alternatives (modify endpoint for restore/copy, column config for exhaustive lists). It also warns about parent schema requirements and includes connector-specific notes, giving clear usage context.

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