get_backend_config

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

With no annotations, the description carries the burden and succeeds by disclosing the fallback behavior, the priority of bucket/region over the environment variable, and the rule to never generate commented-out or placeholder backends. It doesn't cover potential errors but provides essential behavior.

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 purpose sentence, a behavior paragraph, and an Args list. It is moderately detailed but each sentence adds value, and the formatting aids scanning. Slightly longer than necessary but not padded.

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 5 parameters, no annotations, and an interactive workflow, the description covers purpose, all parameters, the return value (JSON with backend block and destination file), and the fallback behavior. It is complete and leaves no major gaps.

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%, so the Args section is critical. It explains each parameter with examples (team: 'platform', project: 'onboarding') and explicitly states that bucket/region take priority over BACKEND_CONFIG, fully compensating for the schema's lack of descriptions.

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 'Obtiene la configuración del backend S3 de un proyecto Terraform', a specific verb and resource. It clearly differentiates from sibling tools like search_modules and scaffold_terraform by focusing on backend S3 configuration.

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 clear workflow guidance: if BACKEND_CONFIG is not defined, the tool returns `needs_user_input`, prompting the agent to ask the user for bucket/region and re-call with those values. It does not explicitly name alternatives, but the context is clear and actionable.

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