agy_exec

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

No annotations are supplied, so the description carries the full burden, and it discloses almost nothing: it never mentions that the default mode 'accept-edits' implies filesystem mutation, nor any sandbox, permission, cost, or rate-limit characteristics. An agent could reasonably assume this is a read-only query tool, which is misleading given the schema defaults.

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?

A single tight sentence with no padding, and the delivery mechanism is front-loaded. It earns its place structurally even though its content is thin.

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 4-parameter execution tool with no output schema, no annotations, and a mutation-implying default mode, the description leaves the agent without the safety and routing context it needs. The critical risk that acg_exec can modify a project directory is nowhere acknowledged.

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 100%, so every parameter is already documented in structured data and the baseline of 3 applies. The description adds nothing about the prompt, model selection, mode, or directory semantics beyond what the schema states.

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?

States a verb (executa) and a resource (comandos/consultas) delivered via the Antigravity CLI, which rules out unrelated tools. But 'genéricos ou arbitrárias' is near-tautological and gives no basis for distinguishing this tool from sibling agy_command, which by name also sounds like command execution.

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?

No statement of when to use this tool versus agy_plan, agy_command, agy_review or agy_validate_tests, and no prerequisites. The only routing hint, if any, lives in the mode enum rather than in the description.

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