Scale instance count

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

Annotations indicate a write operation (readOnlyHint=false) and destructive hint (destructiveHint=true). The description adds meaningful context: it turns off autoscaling and that the value is ignored while autoscaling is active. It also mentions the underlying API call. No contradiction with annotations; the description extends the behavioral profile with useful side-effect information.

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 well-structured with a summary, a link, an API call reference, and usage guidance. The first sentence is slightly redundant with the title, but the rest is focused and every sentence adds value. It is concise enough while providing necessary caveats and alternatives.

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?

Given the tool's moderate complexity and lack of output schema, the description covers the main purpose, a key caveat, the alternative tool, and the API endpoint. It does not describe return values or error conditions, but for a scaling operation this is acceptable. The sibling alternative is named, which helps contextual decision-making.

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 50% (only serviceId has a description). The description adds meaning for numInstances by calling it 'a fixed number of instances' and clarifies the effect of the operation. However, it does not provide validation details or edge-case guidance (e.g., allowed ranges for numInstances), so it only partially compensates for the sparse 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 function: 'Scale the service with the provided ID to a fixed number of instances.' It uses a specific verb ('scale') and resource ('service'), and distinguishes it from the sibling render_autoscale_service by explicitly mentioning the alternative. This makes the purpose 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 provides explicit usage guidance: 'Usage: Sets a fixed instance count and turns off autoscaling. To scale on load instead, use render_autoscale_service.' It also includes an important caveat that Render ignores the value when autoscaling is enabled, telling the agent when not to rely on this tool. This is clear and actionable.

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