aya_templates_congelar

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

With no annotations, the description carries the full burden. It adds a useful behavioral guarantee by stating the operation does not copy or alter the template. However, it does not clarify whether freezing persists any state, whether it is reversible, or what side effects occur beyond that guarantee.

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?

Two short sentences with no filler: the first states the core action, the second eliminates ambiguity about copy/alter behavior. Every word earns its place.

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?

This is a simple tool with three string parameters and no output schema, so the description covers the essential selection context and a key behavioral exclusion. Still, it omits what happens on success, what the response contains, and whether the freeze is persistent, leaving moderate gaps for an agent.

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 description should compensate by explaining the parameters. It only refers to the 'template selecionado' without defining how 'pasta', 'categoria', and 'nome' select the template, their expected formats, or their relationship to each other.

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 names a specific verb ('Congela') and resource ('metadados/hash do template selecionado'), and explicitly clarifies what it does not do ('Nao copia nem altera o template'). This makes it clearly distinguishable from sibling tools like aya_templates_listar and aya_templates_validar_hash.

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 implies the use case: freeze the metadata/hash of a selected template without copying or altering it. However, it never explicitly states when to choose this tool over alternatives or names any sibling, so the guidance remains implicit rather than directive.

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