glue_schema

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

With no annotations, the description carries the full burden of disclosing side effects, permissions, or mutation risk. It says 'Manage' and lists actions like evolve/define, but never states whether catalog schemas are modified, whether operations are reversible, or what side effects occur. The deprecation note adds context but not behavioral 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 well-structured with a deprecation banner, one-line summary, and bold mode subsections that each list only relevant parameters. There is no filler; even the 'Still registered this minor version' line adds availability context.

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 output schema exists and all 14 parameters are covered by mode-based breakdowns, an agent has enough to invoke the tool correctly. Missing is any statement about side effects or exact mode string values, but the mode headings make those inferable.

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 description coverage is 0%, but the description fully compensates by mapping every parameter to its mode, indicating which are required, and adding type guidance ('dict/list') not present in the schema. This is far more informative than the bare property names.

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 clear deprecation warning and a preferred alternative, then identifies the resource (Glue Data Catalog schemas) and three specific actions with concrete outcomes: detect schema and generate table definition, generate evolution strategy, and generate catalog table definition. This distinguishes it from siblings like glue_job and glue_s3 by naming the exact domain and outputs.

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?

It explicitly says 'Deprecated. Prefer glue_job', which tells an agent not to use this tool when a current alternative exists. Mode-specific parameter lists give contextual usage for each mode, though it does not state conditions under which glue_schema should still be used despite the deprecation.

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