platform_tools

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

With no annotations, the description carries the full burden. It discloses pagination behavior (use page and limit), destructive delete behavior (force and confirm, 409 error without force), and test timeout. However, it does not describe the return format, success/error structure beyond the one 409 case, or side effects of create/update operations. The 'Note: tool CRUD routes through the Studio API' adds minor context but is not deeply behavioral.

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 structured with an action list and relevant parameter usage, but it opens with a broad, misleading sentence about managing projects, agents, tools, etc., which is unnecessary and could confuse. The core content is efficient, but the opening wastes words and detracts from the tool's actual purpose, making it less concise than it could be.

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 complex tool with 12 parameters and 6 actions, the description covers key actions and important operational details like pagination, force delete, and test timeout. However, it omits expected return values (no output schema exists), error handling beyond the 409 case, and specifics about the 'definition' object structure for create/update. These gaps leave the agent partially uninformed about full usage requirements.

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 high (92%), so baseline is 3. The description adds practical meaning beyond the schema: it explains page/limit usage for pagination, force/confirm for delete, and timeoutMs for test. These clarifications help the agent understand how to properly use the parameters, going beyond the schema's basic 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 clearly identifies the tool as managing tools within a project, listing six specific actions (list, get, create, update, delete, test). It distinguishes from siblings like platform_projects and platform_agents by focusing on the 'tool' resource. However, the opening sentence unnecessarily broadens scope to projects, agents, configurations, etc., which creates slight ambiguity about whether this tool handles all those entities or just tools.

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?

No explicit guidance is provided on when to use this tool instead of sibling tools like platform_projects or platform_agents. The description implies tool-specific management but the first sentence muddies this by claiming it 'creates and changes projects, agents, tools...' without clarifying that this tool is only for tools. There are no exclusions or alternatives mentioned, leaving the agent to infer the appropriate context.

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