agy_ask

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

No annotations are present, so the description carries full burden. It discloses the --mode plan limitation, inability to edit files, session continuation semantics, and the critical constraint that conversation_id only works for CLI conversations, not IDE ones. This is thorough and trustworthy.

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?

Three sentences, each earning its place: purpose, safety/read-only, and parameter usage. Front-loaded and no filler.

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 four parameters, no annotations, and no output schema, the description covers purpose, safety, and parameter interplay adequately. It doesn't describe return format, but for a chat tool that's acceptable and not a critical gap.

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% with basic descriptions, but the tool description adds relational semantics: session_id continues context, omitting starts new, conversation_id adopts external CLI sessions, and conversation_id is ignored when session_id is present. This goes beyond the schema's individual property 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 a specific verb ('Ask') and resource ('agy (Antigravity CLI)'), clearly distinguishing this as the question/consultation tool. It explicitly notes read-only behavior, which sets it apart from the sibling execute tool.

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?

Provides clear guidance on when to use session_id versus conversation_id, and when to omit them. The read-only caveat implies use for questions rather than actions, but it doesn't explicitly name agy_execute as the alternative for modifications.

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