agy_say

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

With no annotations, the description does real work: it discloses that the conversation auto-resumes when the underlying process has ended, that model/effort inherit from the session, that a new model starts with no effort unless specified, and that changing either restarts the process on the same conversation. That restart side effect is exactly the kind of hidden consequence an agent needs. It stops short of covering failure modes or what a blocking call does on timeout.

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?

Four tight sentences with the core action front-loaded and the caveats (auto-resume, model/effort inheritance, process restart) following in descending order of importance. No filler, though the clause about a new model starting with no effort is dense enough to require a second read.

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?

Return values needn't be described because an output schema exists, and the lifecycle behavior is reasonably covered. For a mutating, potentially process-restarting tool with zero annotation coverage, the missing pieces are the wait_seconds blocking semantics and any error/timeout behavior, which leave the agent unable to predict the cost of a call.

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% across five parameters, so the description must carry the load. It explains model and effort well, including inheritance and restart semantics, and session_id/message are self-evident from their names. However, wait_seconds (default 600) is never mentioned, leaving the agent to guess whether the call blocks, for how long, and what happens on expiry.

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 ('Send the next message in an AGY session') and enumerates the legitimate payload types (fixes with a new diff, answers to AGY's questions, arguments against a finding). That clearly separates it from session-lifecycle siblings like agy_start, agy_resume, and agy_end, though it never names them explicitly.

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?

Usage is implied rather than stated: the agent must infer that this is the tool for continuing an existing conversation rather than opening one or polling one. The note about resuming an ended process gives useful context but is framed as behavior, not as a when-to-use rule. No explicit exclusions or pointers to agy_start/agy_wait for the alternatives.

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