Get or create agent

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

The description goes well beyond the annotations by explaining the idempotent behavior in practice: it returns an existing agent marked 'existing': true instead of creating a duplicate. It also discloses plan limits affecting creation and the fact that model is ignored when an existing agent is returned, adding critical behavioral context not inferable from annotations.

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?

The description is longer than the minimal ideal but each sentence earns its place: it front-loads the core purpose, then covers usage guidance, idempotency, plan limits, and model behavior. It is well-structured and free of fluff, though slightly verbose compared to the two-sentence standard.

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 tool with no output schema, the description thoroughly explains the return behavior (the 'existing': true flag), plan constraints, and when to use this tool. It also handles edge cases like reconnecting to an existing agent, making it complete enough for an agent to invoke correctly.

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?

Since the schema already covers both parameters with 100% description coverage, the description does not need to repeat them. However, it adds a key semantic detail not in the schema: 'model is ignored when an existing agent is returned' and suggests using set_agent_model to change it. This enriches parameter understanding beyond 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?

The description clearly states the tool's purpose with a specific verb+resource: 'Get or create an agent by name: a cloud computer...' It also distinguishes itself from siblings like get_agent by explaining the get-or-create semantics and mentioning 'instead of a duplicate.' This makes the tool's unique role unambiguous.

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 description gives explicit when-to-use and when-not-to-use guidance: 'Create one when the work should accumulate somewhere the user can return to...' and 'You do not need one for a question you can answer yourself or for a one-off script...' It also names an alternative for model changes ('use set_agent_model to change it'), providing clear direction against alternatives.

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