iaas_get_machines

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond an endpoint path — no pagination defaults, no note on how the count/filter flags change the response, and no disclosure of result size limits for what is clearly a large collection.

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 lines say the same thing twice ('Get machines' and 'Get all machines') before a redundant path echo. It is short but the content is almost entirely repetition rather than front-loaded useful 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?

This is a seven-parameter paginated collection endpoint with no output schema, so the description should at least say what a machine record represents and how results are paged by default. Neither is covered, leaving the agent dependent entirely on schema and annotations.

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 100%, so all seven parameters (top, skip, count, filter, select, apiVersion, skipOperationLinks) are already documented in the schema. The description adds no syntax or semantic detail beyond that, which is the baseline case for full coverage.

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 text 'Get machines / Get all machines' restates the tool name and adds only a plural scope hint; it does not distinguish this list operation from siblings like iaas_get_machine, iaas_get_machine_disks, or iaas_get_machine_snapshot. Only the raw endpoint path gives any hint of the resource collection being retrieved.

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?

There is no statement of when to use this list endpoint versus the singular iaas_get_machine or the many other listing tools, and no mention of prerequisites such as authentication or required API version. The agent must infer usage purely from the name.

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