optimization.run

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

With no annotations provided, the description carries the full burden and does well: it discloses an auth requirement (MODELBOUND_API_KEY), states that the server automatically creates a backup version, and warns that local-file edits require a caller-side BackupEngine snapshot first. This is meaningful side-effect and safety disclosure, though reversibility and failure behavior are not addressed.

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 sentences, front-loaded with the action, then outputs, then requirements. No filler; each sentence carries distinct 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?

There are no annotations and no output schema, yet the description covers return fields, auth, backup behavior, and the local-edit prerequisite. The remaining gap is the undocumented ID selection semantics and intensity meaning, but the critical invocation context is present.

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 only 17% (only dry_run is documented), so the description should compensate. It names the four resource kinds, loosely mapping to skill_id/file_id/agent_id/pack_id, but never states that exactly one ID should be supplied nor explains intensity or the version snapshot, leaving most parameters undocumented.

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 ('Run AI token optimization') and the resource types it operates on (cloud skill, file, agent, pack), and the mention of returning a version snapshot id signals it is a mutating run, not a preview. It doesn't explicitly contrast itself with siblings like optimization.dryRun or optimization.preview, so an agent must infer the distinction.

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?

Provides concrete prerequisites: 'Requires MODELBOUND_API_KEY' and the MUST-snapshot requirement for local-file edits. However, it offers no explicit when-to-use/when-not guidance versus optimization.dryRun or optimization.preview, leaving the alternative selection to be inferred from the dry_run parameter.

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