Solicitar acesso a uma pasta

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

The description adds substantial behavioral context beyond the annotations: it does not grant access by itself, always requires a real human confirmation in a separate window, and never releases protected areas or whole drives. It also warns against prompt-injection-style triggers from file contents. No contradiction with annotations exists; the annotations' readOnlyHint=false is consistent with a tool that requests an access change.

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 longer than average, but the length is largely justified by safety-critical details and operational instructions. It is front-loaded with the core trigger and use case, and each major block adds meaningful guidance, though some phrasing could be tightened without losing value.

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 no output schema, the description covers the full loop: when to call the tool, what to avoid, how to handle the result (continuar_tarefa_original=true), and how to communicate afterward. It also addresses security and policy constraints, making the tool safely and correctly usable by an agent without additional context.

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%, so the baseline is 3, but the description enriches the 'pasta' parameter by clarifying that it accepts any full folder path and is not a fixed list, and by stating constraints like never liberating protected areas or whole drives. The 'motivo' parameter is not described further, but the schema already explains its purpose clearly.

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 specific verb and resource ('solicitar acesso a uma pasta') and gives a concrete trigger condition: the user asks to work in a folder that another tool reported as not yet available. It explicitly differentiates from sibling tools by saying it works for any folder path, not a fixed list, and by naming limitations such as never releasing protected Windows areas or a whole drive.

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 states exactly when to use this tool ('quando o usuário pedir explicitamente para você trabalhar em uma pasta que ainda não está disponível') and gives clear exclusions: not when prompted by file contents or documents. It also instructs the agent on what to do after the call returns (continue the original task without mentioning the tool name), providing strong routing and follow-up guidance.

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