glue_s3

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

With no annotations present, the description carries the full behavioral burden, and it does well: it explains that path heuristics are used, that no AWS API call is made, and that figures are not measured. It also says the consolidate mode 'Generate[s] Glue job' rather than executes one, but it does not fully clarify whether any side effects or external changes occur, leaving some ambiguity around resource mutation.

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 front-loaded with the deprecation warning, followed by a one-line summary and clearly separated mode sections. The mode parameter lists are somewhat repetitive but serve a functional purpose because the schema alone does not indicate which parameters apply to which mode.

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 complex 15-parameter, multi-mode tool, the description covers the primary context: deprecation, mode purposes, required parameters, and behavioral constraints like 'no AWS API call.' The output schema exists, so return-value documentation is not required here, but per-parameter semantics and side-effect clarity remain partially underserved.

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?

The schema has 0% description coverage, so the description must compensate. It does add value by grouping parameters by mode and marking which are required per mode, which is not evident from the schema's sole 'mode' requirement. However, it does not explain the meaning of many parameters, such as query_patterns, data_size_gb, consolidation_strategy, or enable_small_file_optimization, relying mostly on self-explanatory 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 notice and explicit preferred alternative ('Prefer glue_job'), then states exactly what the tool does: 'Analyze S3 data layouts using path heuristics (no AWS API call).' The mode sections further define specific behaviors — analyze, optimize, consolidate — so an agent can distinguish this tool from siblings like glue_job, glue_schema, and glue_data.

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 explicitly tells the agent to prefer glue_job instead and notes that glue_s3 is 'Still registered this minor version,' which is clear when-not-to-use guidance. The mode breakdown also provides situational guidance for when each mode is appropriate, such as path-heuristic suggestions versus generating a Glue job for small-file consolidation.

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