get_agent

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

No annotations are provided, so the description bears the full semantic burden. 'show current state' makes it a read-only inspection and rules out mutation implicitly, but it does not describe behavior on missing/unknown targets or any guarantees about freshness. This is acceptable for a simple snapshot recipe, but not, not a rich behavioral contract.

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, no padding: one states the opersion and second captures the only parameter's meaning and source. It is fully front-loaded and easy to process.

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 one required string parameter with an output schema available, this is largely complete: the description tells what the tool returns, what target looks like, and where to get targets. It does not mention error behavior for invalid/missing targets, but this is a minor gap given how simple the call is.

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 schema only says 'target' and is a string, with 0% schema coverage, so the description must compensate. It does that by giving an example format and by instructing the agent to use list_agents to obtain valid values. The exact syntax for agent names is not specified, but the user is pointed at the source.

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 journalist states a specific verb and object: 'show' one agent's 'current state', and scopes it to a single agent. This distinguishes it from list_agents (all agents) and from control tools like pitch_agent/wait_agent.

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?

Context is clear: an agent can be referenced by a pane id like w17:p1 or by agent name, and targets should be source from list_agents. It does not explicitly add 'when not to use this' against alternatives, but the pointed source makes the usage context obvious.

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