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

With no annotations, the description carries the full burden and does it well: it discloses that stopping is non-destructive by default because the session remains resumable, and that forget=True is destructive, deleting the registry entry plus scratch, backup and log files. It omits idempotency and any error behavior for a session with no active process.

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 sentences, front-loaded with the core action and followed by the conditional exception. Every clause adds information; nothing is redundant with the name or title.

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?

An output schema exists, so return values need not be described. For a two-parameter lifecycle tool with a destructive flag, the description covers the main behavioral risk and the default safety profile; only edge-case behavior (no running process, already-ended session) is unaddressed.

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 0%, so the description must supply parameter meaning, and it does for the risky one: forget=True is defined by its concrete side effects (registry deletion, file removal) rather than just 'forget the session'. session_id is left undefined, though its meaning is self-evident from the schema.

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 specific verb and resource ('Stop a session's AGY process') that an agent can map directly onto a session. It is distinguishable from agy_start and agy_resume via the resumability clause, though it never names those siblings 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?

Use is implied: call it to stop a running session, and resumability is noted, which hints at agy_resume as the follow-up. There is no explicit when-not guidance, no stated alternative tool name, and no mention of what to do if no process is running.

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

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

No annotations are supplied, so the description carries the whole burden, yet it never says whether results are cached, how stale the list can get, or what `refresh_models` does behaviorally. It does flag the discovery-only nature implicitly by naming the consuming tool, but the mutating/caching behavior of the single parameter is left entirely opaque.

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, front-loaded sentences with no filler; the model-slug note is a genuinely needed caveat rather than padding. Slight loss for the line break making the second sentence read like a continuation of the first rather than a distinct point.

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?

An output schema exists, so the return payload needs no explanation, and the tool is a simple zero-required-param listing call. The one remaining gap that matters, the meaning of `refresh_models`, is unaddressed, which leaves the definition adequate but not complete.

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% and the only parameter, `refresh_models`, is never mentioned in the description, so the agent must guess whether toggling it forces a remote fetch. The effort-level guidance adds useful meaning but describes downstream slug usage rather than this tool's input.

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 specific verb+resource ('List AGY agents') and also names the second payload (model slugs AGY offers), tying itself to the sibling that consumes agents (agy_start). An agent can distinguish this discovery tool from the action tools (agy_start, agy_say, agy_wait) without opening any schema.

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?

Gives an explicit instruction to always read the list here rather than assume a fixed set, and explains how the returned model slugs should be passed downstream (full slug, or base slug plus `effort`). It stops short of stating when not to call it or when a refresh is warranted.

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

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

No annotations are supplied, so the description carries the full burden; it does disclose the key behavioral trait that the session runs in a fresh process and that the operation is largely redundant with agy_say. It does not say what happens if the bridge cannot resolve the session or whether an already-live session is replaced, which for a zero-annotation tool is a real remaining gap.

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 short sentences, zero filler, with the core action stated first and the routing/alternative guidance following. Nothing repeats the tool name or schema without adding meaning.

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 are covered by the output schema, and the description supplies the selection semantics and the sibling relationship that the schema cannot. The main omission is behavior when no identifier is given at all, since every parameter is optional and the description assumes one of the two IDs will be provided.

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% and all four parameters are undocumented in the schema, so the description must compensate — and it does, explaining that the target is chosen by session_id or conversation_id and that agent and cwd are additionally required for an unseen conversation. It leaves unstated whether session_id and conversation_id are mutually exclusive or which wins if both are supplied.

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 specific verb and resource ('Re-open a stored AGY session') plus the scope ('in a fresh process'), and the identifiers it accepts. It cleanly separates itself from agy_say, which the description explicitly names as an automatic resumer.

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?

Gives an explicit when-not ('agy_say also resumes automatically') and narrows the remaining use case to warming a session up front. It also states the conditional prerequisite for new conversations (pass agent and cwd), so an agent can decide before opening the schema.

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

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.

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

No annotations are supplied, so the description carries the disclosure burden alone. It does contribute one genuine behavioral fact, the default sort order (most recently used first), but says nothing about result capping/pagination or whether the operation is a safe read, which matters for a listing tool.

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 the core action front-loaded and the ordering detail immediately after; no filler or restated title. A brief clause on the limit parameter would have been worth the extra words, but nothing present is wasted.

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?

An output schema exists, so return values need not be described, and the tool is a simple two-parameter lister. Still, for a tool with zero schema description coverage, the omission of the limit parameter's meaning and of any truncation behavior leaves an agent guessing about result volume.

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 must compensate. It explains that 'cwd' means filtering by project, which does add meaning beyond the bare string-typed property, but the second parameter 'limit' (default 20) is never mentioned, leaving half the inputs unexplained in both schema and prose.

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 ('List stored AGY sessions') and adds ordering ('most recently used first'), which separates it from siblings like agy_list_agents and agy_status. It stops short of explicitly naming a sibling or stating the scope of what a 'session' record contains, so it is clear but not fully differentiated.

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 only usage hint is 'Filter by project with cwd', which implies an optional narrowing case but gives no guidance on when to use this versus agy_status or agy_list_agents. There is no mention of the default result limit or what to do when more sessions exist than are returned.

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

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

With no annotations, the description carries the full burden and does well: it discloses the async contract (wait_seconds returns status RUNNING while the turn keeps going, collect with agy_wait) and real side effects (notes include denied actions and files AGY changed). It stops short of stating permission requirements, cost, or concurrency limits for concurrent sessions.

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?

Front-loaded purpose sentence followed by a scannable parameter glossary; every line conveys a distinct, actionable fact. No restatement of the tool name 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?

For a session-creating tool with an output schema, the description covers initiation, async continuation, defaults, and notable side effects. Remaining minor gaps are error conditions (bad cwd, unknown agent) and any session/concurrency limits, though agy_list_agents and agy_status likely cover some of that.

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 0%, so the description must compensate, and it documents all seven parameters: agent with an example, cwd as an absolute path, message contents, model/effort as optional defaults, schema including the default review shape (verdict, summary, findings, questions_for_claude), and wait_seconds semantics. This adds substantial meaning the bare schema lacks.

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 specific verb+resource pair: 'Open a new AGY review session and send the first message.' The word 'new' plus 'first message' implicitly separates it from agy_resume (existing session) and agy_say (follow-up message), so an agent can pick correctly without opening the schema.

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?

Gives clear per-parameter usage context (agent must be installed, cwd is where AGY runs, message must include intent and test instructions) and explains the wait_seconds/wait tradeoff with agy_wait. It never explicitly says when to prefer agy_resume or agy_say over this call, which is the one routing gap given seven siblings.

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

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

With no annotations, the description carries the full burden, and it does convey that the read is a point-in-time snapshot ("right now") rather than a blocking wait, plus the shape of what is reported. It stops short of stating that the call is non-mutating, that it errors on an unknown session, or that it returns immediately rather than waiting for work to finish.

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 sentences, zero filler, with the returned-fields summary front-loaded ahead of the usage hint. Nothing could be cut without losing information.

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?

An output schema exists and the description already sketches the return payload, so return semantics are adequately covered. The remaining gap is operational: which session_id to supply and how this differs from agy_wait or agy_sessions, which matters in a seven-sibling family where several tools touch session state.

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?

The single required parameter, session_id, has 0% schema coverage and is never mentioned in the description. The reader must infer that it identifies which AGY session to report on and where that id comes from (presumably agy_sessions or agy_list_agents), so the description does not compensate for the coverage gap.

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?

Names a specific verb and resource — reports what an AGY session is doing right now — and enumerates the returned facts (idle/working state, current turn, elapsed time, last tool steps). That is concrete enough to separate it from mutating siblings like agy_say or agy_start, but it never contrasts with agy_wait, the closest read-tool alternative.

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?

"Use it when the user asks for progress" gives one clear trigger for invocation. However, there is no when-not guidance and no mention of agy_wait, which an agent could easily confuse with status polling since both concern a session's state over time.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the call blocks ('keep waiting') and that it is idempotent when idle ('returns the last result again if no turn is running') — a non-obvious trait. It says nothing about what happens when the wait expires (error, RUNNING, partial result), despite wait_seconds defaulting to 600, nor about concurrency or rate limits.

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, zero filler, with the blocking behavior and the idle-return behavior front-loaded. Nothing is wasted and the ordering puts the most important behavioral fact first.

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?

An output schema exists, so return values need not be explained. But this is a long-blocking tool with a timed default and no annotations, and the timeout semantics — the single thing most likely to surprise an agent — are absent from the description and unstated in the schema.

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% for two parameters, so the description must compensate and does not: neither session_id nor wait_seconds is mentioned. Worse, 'keep waiting' implies open-ended blocking while the schema exposes a 600-second default timeout, leaving the agent unable to tell whether wait_seconds is a deadline or a polling interval.

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 states a specific verb and resource ('Keep waiting for a turn') and ties the starting state to the sibling tools that produce it ('a turn that agy_start/agy_say returned as RUNNING'), which is concrete. It does not, however, distinguish itself from agy_status, the obvious non-blocking sibling, leaving the blocking-vs-polling distinction to inference.

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 precondition for use is explicit: call this only after agy_start or agy_say reported RUNNING. That is a clear usage context. No exclusions or alternatives are named, so an agent that receives a RUNNING state and only wants a single check has no pointer to agy_status.

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