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

Goes well beyond the annotations by describing the underlying HTTP mapping, the resulting control state ASSIGNED, the persistence of the alert's active status, and the preview behavior when confirmed=False. This adds concrete behavioral context that the annotations alone do not provide.

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?

Every sentence carries useful information: core action and effect, technical endpoint mapping, usage guidance versus cancel_alert, and confirmed-flag behavior. It is front-loaded and has no filler.

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?

The description fully explains the state transition, the endpoint, and the alternative, and it touches on the preview response. Since there is no output schema, a mention of the exact return structure would improve completeness, but the description is still adequate for correct invocation.

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 the baseline is 3. The description reiterates the confirmed flag's preview behavior but does not add any parameter-specific details beyond what the schema already documents.

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?

Description states a specific verb 'acknowledge' and resource 'active alert', immediately clarifying it means taking ownership and not cancelling. It also explicitly maps to POST /alerts?action=takeownership, which leaves no ambiguity about the operation.

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?

Explicitly tells the agent when to use this tool ('Use this when you want to own the alert without closing it') and names cancel_alert as the alternative that closes the alert for good. It also explains the confirmed flag's role in previewing versus actually making the change.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds context beyond those flags: non-idempotency consequences (calling twice adds two notes), the created vs. confirmation_note semantics, and the absence of an undo path. This is useful behavioral disclosure that the annotations alone would not provide.

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?

Well-structured, purpose-first prose with the [WRITE] marker and each sentence carrying weight (routing, idempotency, confirmation, undo). It is slightly long given that annotations already flag idempotency and non-destructiveness, but no sentence is filler.

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 write tool with no output schema, the description adequately covers return values, failure behavior (created null → verify with list_alert_notes), and side-effect expectations (no status/ownership change, no undo). Minor gaps: no error conditions for invalid alert_id or empty note beyond the schema's rejection note.

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 100%, and the schema already explains alert_id ('from list_alerts, not the resource UUID'), the note text, and the target default. The description adds no new parameter-level meaning, so the baseline 3 is appropriate.

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, resource, and intent with a concrete goal (record who is handling the alert and what was done). It explicitly distinguishes itself from acknowledge_alert, and the [WRITE] prefix disambiguates it from the read-only list_alert_notes / get_alert siblings.

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?

Explicitly names acknowledge_alert as the alternative when ownership must be taken, and declares that this tool does not change status or ownership. It also gives a precise when-not-to-retry condition (run list_alert_notes before retrying when created is null).

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

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

Annotations already mark this as destructive, but the description adds important context: cancellation is permanent, cancelled alerts will not re-trigger unless the underlying condition recurs, and confirmed=False only previews without making changes. This goes well beyond the structured annotation data.

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 compact, front-loaded with the core action, and every sentence earns its place: action, permanence, alternative, re-trigger behavior, and preview behavior. There is no filler or redundancy.

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 three-parameter destructive tool with full schema coverage, the description covers what the tool does, when to use an alternative, the permanence of the action, re-trigger semantics, and the preview mechanism. No critical operational detail is missing.

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 the input schema already documents alert_id, target, and confirmed well. The description reinforces the confirmed preview behavior but does not add substantial new parameter-level meaning beyond what the schema provides.

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 uses a specific verb and resource ('Cancel (dismiss) an active alert') and clearly distinguishes itself from acknowledge_alert by noting the difference between dismissing and marking as seen. An agent can tell exactly what this tool does and how it differs from its closest sibling.

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?

It explicitly tells the agent to use acknowledge_alert instead when only marking as seen, and explains when cancellation is appropriate. It also clarifies the confirmed parameter behavior, giving clear operational guidance for when to actually execute versus preview.

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

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

Annotations already establish that this is a write operation, non-idempotent, and non-destructive. The description adds useful behavioral context by stating the return value ('Returns the new definition's id and name') and by requiring that symptom definitions already exist before calling.

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 tightly packed sentences with no filler. The main purpose is first, followed by return value, then prerequisite and alternative routing. Every sentence contributes to correct tool selection or invocation.

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 7-parameter create operation with no output schema, the description covers the essential missing context: what it creates, what it returns, what must be done beforehand, and which sibling to use instead. The remaining parameter details are fully covered by the schema.

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 100%, so all parameters are already described. The description adds practical value beyond the schema by telling the agent to call list_symptom_definitions first for symptom_definition_ids, which directly informs how to populate a required parameter.

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 opens with a specific verb and resource: 'Create a new alert definition referencing existing symptom definitions.' It clearly distinguishes this from the sibling set_alert_definition_state by explicitly warning not to create a variant just to silence an alert.

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 guidance: run list_symptom_definitions first to obtain valid symptom_definition_ids, and use set_alert_definition_state instead when the goal is to silence an existing definition. This is actionable and prevents misuse.

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

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

Beyond the annotations' destructiveHint=true and readOnlyHint=false, the description reveals important behavioral consequences: active alerts generated by the definition are not affected, and confirmed=False provides a preview without mutating state. This is exactly the kind of context annotations alone do not convey.

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?

Four short sentences, each carrying meaningful information: the irreversible action, the non-impact on active alerts, the safer alternative, and the preview default. No filler or repetition, and the destructive nature is front-loaded.

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 destructive tool with a confirmation parameter, the description is fully complete: it tells the agent what is deleted, why to prefer an alternative when uncertain, and how to preview before committing. With no output schema required, nothing essential is missing.

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 100%, so the schema already documents all three parameters. The description adds semantic value by explaining the confirmed=False preview behavior, which recontextualizes the confirmed parameter's role. target remains only schema-documented, but that is acceptable given its simple default behavior.

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 states a specific verb ('delete') and resource ('alert definition'), and immediately clarifies permanence: 'Permanently delete... Irreversible.' It also distinguishes itself from the sibling set_alert_definition_state by explicitly positioning that as the non-destructive alternative.

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 explicitly tells the agent when NOT to use this tool: use set_alert_definition_state(enabled=False) instead to silence a definition that may later be needed. It also explains the confirmation flow, making the intended usage pattern clear.

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

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

The description goes well beyond the annotations by disclosing that deletion is irreversible, is recorded in the audit log, returns an error for invalid report_id, and defaults to a non-destructive preview unless confirmed=True. It also clarifies exactly what is and is not removed, which is critical for a destructive operation.

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 dense but every sentence adds essential information: what is deleted, what survives, irreversibility, audit logging, error behavior, and the preview default. The [WRITE] prefix and front-loaded main action make it easy to scan.

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 destructive, non-idempotent tool with no output schema, the description covers the critical operational context: preconditions (list_reports), consequences (permanent deletion, audit log), and safety mechanism (confirmed flag). An agent has enough information to invoke it correctly and understand the side effects.

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?

The input schema already describes all three parameters with full coverage, including the confirmed flag and report_id semantics. The description reinforces these details (e.g., confirmed=False means preview, report_id must be a valid UUID) but does not add substantial new parameter-level meaning 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: 'Permanently delete a generated report artifact from Aria Operations.' It distinguishes the report instance from the report definition and schedules, which differentiates this from sibling tools like delete_alert_definition and get_report.

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 guidance: use list_reports to find valid UUIDs first, use generate_report to recreate the artifact, and note that confirmed=False only previews the deletion. This clearly communicates when and how to invoke the tool versus alternatives.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond those: the refusal behavior for known non-maintenance states, the null before.in_maintenance for unknown states, the confirmed=False preview behavior, and the recording condition. It does not contradict the annotations. A small gap is that it doesn't detail what happens to collected data or alerting during the transition, but the provided context is strong.

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 compact and front-loaded with the core purpose, then covers refusal, unknown-state behavior, return fields, preview mode, and undo in a tight sequence. Every sentence adds information. It is slightly dense and could be split into clearer sentences, but it earns its place with no filler.

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 write tool with no output schema, the description covers the key behavioral nuances: refusal conditions, unknown-state handling, preview mode, return fields, and undo. It does not describe error cases (e.g., invalid resource_id) or the exact shape of the note, but the provided context is sufficient for an agent to invoke it correctly in most cases.

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 the schema already documents all three parameters. The description adds meaning by explaining the confirmed flag's preview semantics ('Default confirmed=False returns a preview without connecting') and by clarifying resource_id is a UUID from list_resources. It doesn't add much about target, but the schema already covers it. This exceeds the baseline 3 by tying parameters to behavior.

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 opens with a specific verb and resource: 'Take one resource out of maintenance so Aria resumes alerting on it and collecting its data.' This clearly distinguishes it from its sibling start_resource_maintenance, and the [WRITE] prefix plus the rest of the description make the operation 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 explicitly states when the tool refuses (resource not in maintenance), when it proceeds (unknown state), and names the undo alternative: 'Undo: start_resource_maintenance (re-enters as manual maintenance).' It also explains the confirmed flag's role in preview vs. actual execution, giving an agent clear decision criteria.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds useful behavioral details: filters are comma-separated, omitted filters match all, and results arrive as finding summaries in a paginated envelope. This gives the agent a realistic expectation of output shape without contradicting the 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 compact and front-loaded: the first sentence states the action and resource, the next gives usage context, then filter behavior, return shape, and a useful compliance disclaimer. Every sentence earns its place, and there is no redundant restatement of schema fields.

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 read-only list tool with no output schema, the description does a good job: it names the returned fields, mentions pagination, and explains filter semantics. The main gap is that the paginated envelope is not further described (e.g., how to request subsequent pages), but the optional limit parameter and schema already cover enough for a first invocation.

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?

The schema already covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds semantic value by explaining the shared filter convention ('comma-separated strings; omit a filter to match all') and states what the returned summaries contain, which helps the agent reason about how the optional filters map to results. This exceeds the baseline.

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 opens with a specific verb-resource pair — 'List Operations diagnostic findings' — and clarifies the domain by naming example content ('misconfigurations, health rule hits') and the returned summary fields. It also explicitly distinguishes this tool from compliance benchmark results, which prevents confusion with a closely related category. The purpose is unambiguous even without sibling-specific comparison.

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 says clearly when to use the tool ('review current diagnostic findings') and gives an explicit exclusion ('NOT compliance benchmark results') with a routing suggestion to vmware-harden. However, it does not contrast this tool with nearby siblings such as list_alerts, list_anomalies, or investigate_alert, leaving some alternative-selection work to the agent.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only: it does not renew or replace any certificate.' It also goes beyond annotations by disclosing the return envelope and the defensive field-reading gotcha, which is genuinely useful behavioral 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 compact and efficiently organized: purpose, use case, return format, read-only caveat, and a practical gotcha are each covered in distinct, information-dense sentences. There is no filler or repetition of schema content.

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 read-only list tool with two optional parameters and no output schema, the description fully prepares an agent: it names the returned summary fields, the pagination envelope, the read-only nature, and a real behavioral caveat. Nothing essential for invoking the tool is missing.

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% and both parameters, limit and target, are already fully documented with defaults and meaning in the input schema. The description adds no new parameter-level guidance, so the baseline score of 3 is appropriate.

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 opening sentence, '[READ] List certificate status and expiry across the VCF fleet', states a specific verb, resource, and scope. It is clearly about certificates across VCF components, which is distinct from alert, finding, and resource siblings, though it does not explicitly name an alternative or say what falls outside its scope.

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?

'Use this to spot certificates that are expired or expiring soon across all VCF components managed by Operations 9.1' gives an explicit, concrete selection condition. It does not mention when not to use it or point to an alternative such as a renewal tool, but for a listing tool the usage context is clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the paginated return envelope, the exact domain summary fields, the meaning of configuration_state values, the 404 behavior for a wrong integration_id, and the critical 'note' gotcha where an empty list means UNKNOWN rather than no domains. This is rich behavioral disclosure that significantly helps an agent interpret results correctly.

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 dense but every sentence earns its place: intent, source of the required parameter, return fields, error semantics, and the critical empty-list gotcha. The '[READ]' prefix and front-loaded purpose make scanning easy, and there is no redundant filler.

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?

With no output schema, the description fully compensates by enumerating the returned fields, status values, pagination behavior, and error cases. It also warns about the ambiguous empty-response case, which is exactly the kind of contextual information an agent needs to avoid misreporting results.

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?

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds valuable context for integration_id by pointing to the exact UI location for the UUID and explaining the 404 meaning, going beyond the schema's 'UUID of the registered VCF integration'.

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 starts with '[READ] List the SDDC/workload domains behind one registered VCF integration', using a specific verb and resource. It clearly distinguishes this tool from siblings like fleet_certificate_list and fleet_password_account_list by scoping it to VCF integration domains, so an agent can select it without ambiguity.

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 explicitly says 'Use this to enumerate the domains of a VCF integration registered in Operations' and explains that the integration_id must be supplied by the operator because 'this skill does not list VCF integrations'. It provides clear context and a practical exclusion, though it does not name alternative tools for when this tool is not appropriate.

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

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

Beyond annotations, the description discloses the return payload shape (username, resource, status, expiry, last_rotated), the paginated envelope, and a defensive-read behavior where unknown fields degrade to empty. It also reinforces the readOnlyHint by explicitly stating the rotation endpoint is not wired in. Nothing contradicts the 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 compact, front-loaded with a clear summary, and each sentence serves a distinct purpose: scope, usage, returns, safety, and a gotcha. No filler or repetition; the operational caveat about defensive field reading is valuable and earns its place.

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?

Considering there is no output schema, the description does a good job by naming the returned per-account fields and mentioning pagination. It could specify pagination mechanics in more detail, but with only two optional parameters and full schema coverage, an agent has enough to call the tool correctly. Minor gaps are acceptable here.

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 100%, and both parameters have meaningful descriptions: limit defaults to 50 and None returns all; target selects the config target. The description's mention of the paginated envelope is related to limit but adds little beyond what the schema documents, so the baseline of 3 is appropriate.

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 first sentence states the exact scope and action: 'List managed password-account status across the VCF fleet.' It clearly identifies the resource (password-account status), distinguishes it from sibling list tools like fleet_certificate_list and fleet_domain_list, and is not a tautology.

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 explicitly says when to use it ('Use this to review which fleet accounts Operations manages and their rotation/expiry status') and even gives a when-not: it never rotates or sets a password, and the rotation endpoint is deliberately not wired in. It does not explicitly name alternative tools, but the context and sibling list make the tool's niche clear.

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

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

Annotations already signal readOnly=false, idempotent=false, and destructive=false. The description adds crucial context beyond those flags: the tool returns immediately with a report_id and PENDING status, does not wait for the file, and requires polling. This is exactly the behavioral nuance an agent needs and cannot infer from annotations alone.

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?

Two compact, well-structured sentences. The first states purpose, and the second explains the async workflow and follow-up action. No filler or redundant repetition of the schema.

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?

With no output schema, the description fully explains what the tool returns (report_id, PENDING status) and how to complete the workflow (poll get_report until COMPLETED, then use download_url). For an async trigger tool with rich schema descriptions, this is complete enough for an agent to invoke it 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?

Schema description coverage is 100%, so the baseline is 3. The main description adds no parameter-level detail; however, the schema itself provides rich guidance (resource_ids first-ID semantics, list_resources, definition_id via list_report_definitions). Note a minor schema inconsistency: resource_ids is declared optional but its description says 'REQUIRED', which could confuse agents, but this is not a failure of the main description.

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 operation ('Trigger generation'), the resource ('a report from a report definition template'), and the asynchronous behavior. The [WRITE] tag and the focus on generation distinguish it from read-oriented siblings like get_report and list_reports.

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 explicitly tells the agent how to use the tool and what to do next: poll get_report(report_id) until status == COMPLETED, then use download_url. It implies the division of labor between generation and retrieval, though it does not explicitly state when not to use alternatives.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds significant behavioral context: it details the cost (paging through symptoms, batching), the gotchas around empty vs. unknown lists (symptoms_note, symptom_definitions_note), the fact that the Alert model does not carry a resource name, and where recommendations live. This goes far beyond the annotations and provides crucial runtime behavior. No contradiction with 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 long but every sentence carries important information, covering purpose, usage, return details, cost, gotchas, and related tools. It is front-loaded with the core purpose and then organized logically. While it is verbose, it is not redundant or wasteful, and the length is justified given the complexity of the tool. A score of 4 reflects its efficiency for its length.

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?

The description is exceptionally complete. With no output schema, it explains the full return shape (fields like name, criticality, status, symptoms, notes), the cost implications, edge cases (unknown vs. empty), and relationships to other tools (get_resource, investigate_alert, acknowledge_alert, cancel_alert). It covers everything an agent needs to invoke the tool correctly and interpret the results, making it fully contextual.

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?

The input schema covers both parameters with 100% description coverage: alert_id is described as 'The alert UUID (from list_alerts)' and target as 'Aria target name from config; default when omitted.' The description adds a small clarification that alert_id comes from list_alerts, but it does not significantly expand on the schema. Since the schema already provides full parameter documentation, a baseline of 3 is appropriate.

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 specific purpose: 'Get full details for one alert by UUID, including its contributing (triggered) symptoms.' It distinguishes itself from list_alerts by explicitly saying to use it after list_alerts for drilling into a single alert, and it names the sibling investigate_alert for correlation. This leaves no ambiguity about what the tool does.

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 explicitly provides usage guidance: 'Use this after list_alerts to drill into a single alert; use list_alerts to discover or filter them.' It also mentions alternative tools for acting on the alert (acknowledge_alert, cancel_alert) and for resolving resource names (get_resource, investigate_alert). This clearly indicates when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral details beyond that: the four possible statuses ('found', 'partial', 'none_defined', 'unknown') and their exact implications for the 'recommendations' field (e.g., null vs []). It also warns that 'unknown' must not be interpreted as 'no recommendations'.

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 dense but well-organized. It front-loads the purpose, then details the return fields and statuses in a structured way. Every sentence adds necessary information, and there is no fluff.

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?

Despite no output schema, the description fully specifies return fields, statuses, and their meanings. It covers edge cases and potential errors, making it complete for an agent to understand what to expect. The only minor gap is the 'target' parameter's usage, but it is well covered by the schema.

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 100%, so the schema already explains both parameters. The description adds crucial semantics for 'alert_id' by specifying it must be an alert UUID from list_alerts (not a resource UUID), which is not in the schema and prevents a common mistake.

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 states a specific verb ('get'), a clear resource ('recommendations for one alert'), and explains the mechanism ('resolving the alert to its alert definition'). It distinguishes itself from siblings like 'investigate_alert' and 'list_rightsizing_recommendations' by focusing on Aria's prioritized recommendations.

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 clearly indicates when to use this tool (for getting Aria's specific recommendations for a single alert) but does not explicitly exclude alternatives or mention when not to use it. However, the purpose is distinct enough that an agent can infer usage.

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

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

Beyond the annotations (readOnly, idempotent), it reveals important behavior: overall_status OFFLINE alone is not an outage, UNKNOWN means breakdown unreadable, a 503 is reported rather than raised, and it distinguishes stale data. This is exactly the non-obvious behavior an agent needs.

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 dense and front-loaded with the main purpose, then return semantics and edge cases. It is longer than a minimal description, but the extra clauses each carry operational value, especially given there is no output schema.

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?

With no output schema, the description fully covers return values and their meanings, version format implications, error behavior, and stale-data follow-up. An agent has enough context to invoke and interpret the result 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?

Schema description coverage is 100%, and the parameter is self-explanatory ('Aria target name from config; default when omitted'). The tool description adds no parameter-level semantics, so the baseline of 3 applies.

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 opens with a specific verb and resource: 'Check Aria Operations platform health, per service, plus its version.' It also defines the four assessment states (HEALTHY, DEGRADED, DOWN, UNKNOWN), which clearly differentiates this platform-wide check from sibling tools such as get_resource_health and get_capacity_overview.

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?

It conveys when to use the tool: as a health/version check before relying on 9.x-only tools, and routes to list_collector_groups when HEALTHY data looks stale. It does not spell out a full when-not-to-use set, but the context is clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behaviors: missing values appear in a missing list rather than as zeros, null watchdog_restarts means unknown (not zero), nodes null with nodes_error means unrecognized objects, and error fields (units_error, latest_error, etc.) flag failed reads. It also clarifies memory_pressure.level is an indicator, not a diagnosis. No contradictions with 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 well-structured with clear sections: a one-line summary, 'When' guidance, 'What' output details, and 'Gotchas'. It is front-loaded with the core purpose and uses bullet-like formatting for readability. Every sentence earns its place, providing necessary details without fluff.

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 complexity of the tool (multiple metrics, units, per-node data, memory_pressure levels, error handling) and the absence of an output schema, the description is exceptionally thorough. It explains what each value includes (latest, latest_time_ms, unit, window stats), defines units per metric type, and covers edge cases and error conditions. An agent has enough context to call it correctly and interpret results.

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?

The input schema already documents both parameters (target and window_hours) with 100% coverage, including default values and valid ranges. The tool description adds no new parameter-level meaning beyond what the schema provides, so it meets the baseline of 3 for full schema coverage. It does not mention the parameters explicitly beyond referring to window_hours in the output context, but that is not additional parameter semantics.

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 opens with a specific verb-resource pair: '[READ] Memory, swap, heap and watchdog restarts of the Aria Operations node(s) themselves.' It clearly distinguishes from siblings by naming get_aria_health and list_adapters as alternatives. An agent can immediately tell what this tool does and how it differs.

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?

Explicitly provides when to use this tool: 'When get_aria_health shows a service in ERROR, or the Aria UI/API is slow'. It also gives an exclusion: 'For data that stopped arriving from vCenter or another source, use list_adapters instead.' This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral detail beyond annotations: it notes that values are None while capacity analytics are warming up on a fresh instance, and it identifies the data source (OnlineCapacityAnalytics metrics). This is useful non-obvious context.

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 appropriately sized for the tool's complexity and front-loads the core action and outputs in the first sentence. The caveat about warming up and the sibling routing guidance each earn their place. No filler or repetitive content is present.

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 is no output schema, so the description carries the burden of explaining return semantics. It covers the key values (capacity_remaining_pct, per-dimension absolute remaining, days-until-full), the warm-up None behavior, and the data source. Given the simplicity of the input parameters and the annotations, the description is complete enough for correct selection and invocation.

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%, and both parameters already have descriptions: cluster_id is 'The cluster resource UUID (ClusterComputeResource, from list_resources)' and target has a default and config-origin note. The description adds little parameter-level meaning beyond the schema, so the baseline of 3 applies.

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 states a specific verb ('Returns a capacity overview') and resource ('a cluster'), and precisely identifies the output components: group-level capacity_remaining_pct, per-dimension absolute remaining capacity, and projected days-until-full. It further distinguishes itself from sibling tools by naming what it includes and where it comes from, so an agent can clearly tell it apart from get_remaining_capacity and get_time_remaining.

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 explicitly says 'Start here when assessing overall cluster capacity health' and provides concrete alternatives for more focused needs: 'for absolute headroom values use get_remaining_capacity, and for just the exhaustion projections use get_time_remaining.' This gives the agent an unambiguous routing rule for when to use this tool versus its siblings.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: the output shape, per-dimension units, the OnlineCapacityAnalytics source, and the caveat that values are None while analytics warm up.

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, each earning its place: purpose, return shape and caveat, and sibling routing. The read marker is front-loaded and there is no filler.

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 is no output schema, but the description covers the key returned fields, units, group-level behavior, warm-up nulls, and alternative tools. For a simple 2-parameter read-only analytics query, this is enough for an agent to invoke it 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?

Schema description coverage is 100%, so both parameters are already fully documented. The description adds minor context about cluster/host scope and group-level percentage, but does not need to restate parameter meanings. Baseline 3 is appropriate.

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 opens with a clear read verb and resource scope: 'Get remaining capacity headroom for a cluster or host.' It also names sibling alternatives, so an agent can distinguish this from get_capacity_overview and get_time_remaining without inspecting schemas.

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?

It states precise selection context by noting capacity_remaining_pct is only available at group level, and explicitly routes to get_capacity_overview for the combined view or get_time_remaining for projected days-until-full. This gives actionable when-to-use and alternative guidance.

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

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

With annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds significant behavioral context: URLs are always constructed even when PENDING, download_url must be gated on status, completion_time has appliance-specific formatting, and title/description depend on the report definition. This goes well beyond the 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 front-loaded with the core purpose and then enumerates return fields and edge cases. It is somewhat long but every sentence carries useful operational detail, so the length is justified.

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 is no output schema, so the description carries the full burden of explaining return values. It exhaustively lists fields, statuses, null cases, time formats, and the key caveat about URLs being present before completion. Nothing an agent needs to call this correctly is missing.

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 the schema already documents both parameters. The description reinforces that report_id comes from generate_report or list_reports, but adds little beyond the schema. Baseline 3 is appropriate.

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 opens with a specific verb+resource: 'Get status and download URLs for a generated report.' It clearly identifies the tool's subject (reports) and its outcome (status and URLs), and the detailed return-field list distinguishes it from related siblings like generate_report and list_reports.

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 explicitly says 'Use this to poll after generate_report', giving a clear usage context. It does not explicitly name alternatives to avoid, but the polling role and the mention that report_id comes from generate_report or list_reports sufficiently guide selection.

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

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

Annotations already convey readOnly/idempotent/non-destructive, so the description does not need to repeat that. It adds useful behavioral context beyond the annotations by detailing the shape of the returned object, the badge scoring range, and the null condition when Aria has not scored a badge. This helps the agent reason about output without an output schema.

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 dense sentences carry a lot of value: the first summarizes the return payload, the second positions the tool in a workflow and states its key limitation, and the third routes to alternatives. There is no filler, and the most decision-relevant fact (the UUID-only restriction) is front and center.

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 simple read tool with one required parameter and no output schema, the description fully compensates for the missing output schema by listing all returned fields and the badge structure. It also covers usage context, parameter source, and sibling alternatives. Nothing an agent needs to invoke this correctly is missing.

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 100% for both parameters, so the baseline is 3. The description adds extra semantic value by explicitly noting that resource_id must be a UUID obtained from list_resources and that the tool 'does not accept a name,' which prevents callers from passing a human-readable identifier. This is meaningful clarification beyond the schema description.

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 opens with a clear verb and resource: 'Returns one resource object', then enumerates the exact fields returned so an agent knows what to expect. It explicitly distinguishes itself from get_resource_health and get_resource_metrics, making it easy to tell apart from sibling 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?

It states exactly when to use it: 'Use this after list_resources to inspect a single UUID in depth', and gives an explicit exclusion: 'it does not accept a name, so use list_resources to discover UUIDs by kind or name.' It also names the specific sibling tools for badge-only or time-series needs, leaving no ambiguity about routing.

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

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

Annotations already establish read-only/idempotent safety, but the description adds substantial behavioral context beyond that: null/-1 semantics, badges measuring attached alerts rather than service state, a down service showing HEALTH GREEN 100, and service-object fields with advice to 'Read available, not the badge.' This is rich, non-obvious behavior that an agent cannot infer from annotations alone.

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 front-loaded with the core purpose, then provides usage guidance, then edge-case semantics. Every sentence carries meaningful information; even the caveats about null scores and service objects earn their place given there is no output schema.

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 there is no output schema, the description compensates thoroughly: it names the returned scores, explains null/-1, describes badge scope, covers the service-object variant, and notes included fields like name and kind. An agent has enough context to interpret the result 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?

Schema coverage is 100%, so the baseline applies: both target and resource_id are already documented in the schema. The description does not add new parameter-level detail, but none is needed because the schema is complete.

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 opens with a specific verb+resource: 'Get the health, risk, and efficiency badge scores for a resource.' It distinguishes itself from siblings by explicitly comparing to get_resource and list_alerts, so an agent can tell them apart.

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?

It states when to use this tool ('when the scores are all you need') and names the alternatives: get_resource for the whole object and list_alerts for what drove a low score. It also gives a concrete call example for list_alerts, making routing unambiguous.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses key behaviors: raw vs summary output shape, missing-key reasons, a cap on change points, and an explicit warning never to report a missing key as zero. This adds substantial context over structured 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 dense and front-loaded, but it is one long paragraph with nested details. It has no fluff, but it could benefit from bullets or a slightly tighter structure; still the length is justified by the tool's complexity.

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 no output schema exists, the description fully explains return values: raw points, summary statistics, missing modes, and cap limits. Combined with the schema and annotations, the agent has enough to call it correctly, including edge cases like missing keys.

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 100% and the schema already documents each parameter, so baseline 3 applies. The description adds meaningful semantic detail for summary and metric_keys by explaining the raw/summary response structure and missing-key outcomes, though it does not add extra meaning for hours, target, or rollup_type.

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 explicitly says it fetches time-series metric statistics for a resource and contrasts raw versus summary modes, which distinguishes it from sibling tools like get_resource_health. It also mentions return and missing content, so an agent can tell what this tool is for without opening the schema.

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?

It gives actionable guidance: prefer summary=True for windows over a few hours, and directly names get_resource_health as the alternative for a single current score. This is an explicit when/alternative pairing that helps the agent know which sibling to choose.

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

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

Annotations already set readOnlyHint=true, destructiveHint=false, so description doesn't need to repeat that. It adds useful behavioral details: always returns rows (never empty), pages with next_offset, missing resource is a 404. This goes beyond annotations, though it could mention if errors are returned as exceptions.

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?

Well structured: starts with a clear purpose, includes examples inline, and ends with pagination and error behavior. Slightly dense due to inline property paths, but each sentence adds value. No fluff.

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 has 5 params, full schema coverage, and no output schema, the description covers what the tool returns (rows, next_offset, errors), pagination, and error semantics. It's complete for an agent to call it correctly and interpret results.

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 100%, so all parameters are documented in the schema. The description adds clarity for offset by mentioning passing back next_offset, and for name_filter by giving an example, but it doesn't explain how target is used beyond 'Aria target name from config'. Baseline 3 is appropriate.

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 it retrieves current property values for a resource, listing specific categories (power state, parent host, vCenter, CPU/memory, extraConfig flags) and provides example property paths. This distinguishes it from siblings like get_resource_metrics and get_resource.

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?

It explicitly says to use this for configuration facts and to use get_resource_metrics for time-series values, giving a clear when-to-use and when-not-to-use. This is direct routing to the correct sibling.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness, lowering the bar. The description still adds real behavioral value beyond those: the paginated envelope with next_offset mechanics, the ALL-mode quirk where direction is null when PARENT/CHILD labels could not be read (with direction_note explaining why), and the strong error semantic that a failed read is an error, never an empty list. No contradiction with 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?

Two dense paragraphs that are well front-loaded: the purpose and row format lead, followed by pagination and edge-case semantics. No filler or repetition of the name/title. It earns each sentence, though it is information-dense enough that it borders on needing a structure break for readability.

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?

With no output schema, the description correctly carries the burden of explaining return values — it lists the row fields (id, name, kind, adapter_kind, direction) and the pagination envelope. It covers the ALL edge case and error behavior. The only minor gap is that the target parameter is left entirely to the schema, which already documents it. For a 5-param, no-output-schema tool, this is largely complete.

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 100%, so the baseline is 3. The description adds modest value over the schema: it ties offset to the returned next_offset, and explains the relationship_type=ALL behavior (null direction with direction_note). It also notes resource_id comes from list_resources, which the schema already states. The parameter contracts are well documented in the schema, and the description's added meaning is marginal but real.

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 states a specific verb and resource ('Navigate the inventory: resources related to one resource') with concrete relationship examples (VM -> host, datastore, folder; host -> VMs, datacenter). It also enumerates the output row fields, which clearly distinguishes it from siblings like get_resource, list_resources, get_resource_properties, and get_resource_metrics. The purpose is unmistakable.

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 traversal guidance is explicit: 'Call again on a returned id to walk further up or down' and the pagination contract ('pass it back as offset until null'). The relationship examples give an agent a concrete sense of when this tool applies. However, it never names alternatives or states when NOT to use it versus get_resource/list_resources, so exclusion guidance is left to inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by specifying the return fields risk_score and risk_color, the null behavior when Aria has not computed a badge, and the limitation that the badge does not explain what is wrong. This goes beyond the annotations and gives the agent useful behavioral expectations.

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, front-loading the core purpose and using short, information-dense sentences. It covers purpose, return values, usage guidance, null cases, and alternatives without redundancy or filler.

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 simple read-only tool with one required parameter and no output schema, the description fully covers what an agent needs: what the score means, what fields are returned, when the value is null, and which sibling tool to use for more detail. The annotations and schema handle the remaining context.

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?

Input schema coverage is 100%, so the schema already documents resource_id as 'The resource UUID' and target as the Aria target name. The description does not add significant parameter-level meaning beyond that, so the baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Get the risk badge score for a resource', which clearly identifies the operation. It also distinguishes itself from the sibling get_resource_health by noting it returns only the risk number, not health and efficiency.

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 explicitly states when to use this tool: 'Use this when the risk number is all you want.' It also names the alternative get_resource_health and provides a use-case boundary, and directs users to list_alerts when they need contributing alerts, covering both when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description's [READ] prefix reinforces without contradiction. Beyond annotations, the description adds two valuable behavioral disclosures: the output is structured per dimension (cpu, mem, diskspace) and the crucial 'None does not mean unlimited' warm-up caveat, which prevents a likely misinterpretation. It stops short of 5 by not covering error or edge-case behavior, but the additions are meaningful.

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?

Four sentences, each earning its place: purpose, return structure, sibling routing, and the None caveat. The [READ] tag and primary purpose are front-loaded. Slightly more verbose than strictly necessary, but no wasted content.

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?

With no output schema, the description correctly carries the burden of explaining return values (per-dimension projected days until full) and covers the warm-up None case. Simple parameters are fully documented in the schema, annotations cover safety, and sibling routing is present. An agent has what it needs to select and invoke this tool 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?

Schema description coverage is 100% — both resource_id ('The resource UUID (typically ClusterComputeResource)') and target ('Aria target name from config; default when omitted') are already documented. The description adds no parameter-level detail beyond the implicit mapping of 'cluster' to resource_id, so the baseline 3 is appropriate.

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 opens with a specific verb+resource ('Predict when a cluster will exhaust its capacity based on usage trends') and names the return value (time_remaining per capacity dimension). It explicitly differentiates from get_capacity_overview ('this tool returns only the projections'), so an agent can distinguish it from siblings without opening schemas. The [READ] prefix also signals operation type.

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 an explicit routing rule: 'Use get_capacity_overview instead when you also want current headroom — this tool returns only the projections.' This states both the condition and the alternative, leaving no inference needed. The sibling context confirms get_capacity_overview is the right comparison tool.

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

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

Annotations already indicate readOnlyHit, idempotentHint, and destructiveHint, but the description goes far beyond them. It details the paginated envelope, explicitly tells the agent to check 'truncated' before treating the collection as complete, explains excluded_no_data and hint for no-data resources, describes the meaning of value as the last-hour average, and clarifies latest_value and descending order.

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 dense but well-structured: purpose and chaining first, then a detailed result semantics paragraph. Every sentence earns its place; it is slightly long due to the no-data/envelope explanation, but this is necessary since no output schema exists.

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?

With no output schema, the description takes on the burden of explaining the response envelope, pagination, truncation, and no-data semantics—which it does. It also covers the natural follow-up call to get_resource_metrics. The only gap is the absence of explicit alternative/comparison context, but the tool is fully callable.

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?

Input schema coverage is 100% with descriptions and examples for all parameters (top_n, target, metric_key, resource_kind). The description adds no additional parameter-level semantics, so the baseline schema coverage score applies.

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 opens with '[READ] Query resources with highest consumption of a given metric' and explicitly tells the agent to call get_resource_metrics on a returned id for its history. This gives a specific verb, resource, and metric scope while distinguishing it from siblings like list_resources and get_resource_metrics.

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 clearly states that you use this to query top consumers and then chain to get_resource_metrics, so usage is implied. However, it does not provide explicit when-to-use/when-not-to-use guidance or compare alternatives, such as 'use list_resources instead of get top consumers'.

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

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

The description goes well beyond annotations by disclosing internal steps (fetches alert, reads resourceId, fetches resource, confirms name/kind), the five returned keys, null degradation for unresolvable resources, and the alert_id vs resource UUID gotcha. It even mentions the cost of GET /symptoms. No contradictions with readOnly/idempotent hints.

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 dense but each sentence earns its place: purpose, mechanics, return keys, and gotchas. It is front-loaded with the primary purpose, though the return-key detail makes it somewhat long for a quick read.

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 composite tool with no output schema, it thoroughly covers return fields, edge cases, and a critical caution, giving an agent everything needed to invoke it correctly and interpret results.

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 100%, so the schema already documents both parameters. The description reinforces the alert_id gotcha but adds little beyond schema; baseline 3 is appropriate because the description doesn't materially enhance parameter understanding.

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 core action: 'Resolve one alert to its affected resource in a single call' and explicitly contrasts it with chaining get_alert then get_resource, making its unique value obvious among siblings.

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?

It explicitly directs when to use this tool ('use this instead of chaining get_alert then get_resource') and adds a caution about matching against vCenter inventory unless correlation.confirmed is true, guiding safe and correct usage.

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

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

The description adds extensive behavioral context beyond the readOnlyHint/idempotentHint annotations: the stale threshold logic (3 intervals + 15 minutes), the clock references (appliance vs local), pagination semantics (next_offset null termination), and the gotcha that recent last_collected does not prove all objects receive data. It also discloses that empty/unrecognised answers are errors, not empty lists. No contradiction with 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?

Though lengthy, the description is well-organized into When/What/Gotchas sections and front-loaded with the core purpose. Every sentence earns its place — the field listing compensates for the missing output schema, and the stale and clock explanations are essential. No fluff or redundancy.

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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: row fields, stale/stale_basis logic, clock references, the paginated envelope with next_offset termination, and error behavior. For a read tool with 4 documented parameters and rich annotations, nothing an agent needs to call it correctly is missing.

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 100% and each parameter already has a solid description (limit range, offset pass-through, target config, adapter_kind case-insensitivity). The description reinforces limit/offset usage through the pagination envelope explanation and introduces adapter_kinds_present which helps interpret the adapter_kind parameter. It adds context but doesn't dramatically extend schema semantics.

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 opens with a specific verb+resource pair: 'List Aria Operations adapter instances and when each last collected.' It distinguishes itself from sibling tools like list_collector_groups (collector processes) and get_aria_node_resources (node memory), making its scope unmistakable.

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?

It explicitly names when to use: 'When: an alert such as "Objects are not receiving data", or metrics that stopped updating', and names alternatives: 'For the collector processes behind them use list_collector_groups; for the Aria node's own memory use get_aria_node_resources.' No inference required.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds valuable behavior beyond that: criticality is derived from states[], there is no top-level criticality/enabled field, pagination uses a specific envelope, limit out-of-range is rejected rather than clamped, and truncated should not be looped on. This is exactly the kind of non-obvious behavior agents need.

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 long but every sentence carries operational value: purpose, model quirk, pagination envelope, exact paging rules, and a warning against a common loop. It is front-loaded with the [READ] signal and the core purpose before diving into details.

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 read-only list tool with no output schema, the description fully covers the return envelope, pagination contract, edge cases, and how the results connect to sibling tools. Nothing needed to call it correctly is missing.

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 100%, so parameters are already documented. The description adds meaningful pagination semantics for limit, offset, and next_offset beyond the schema, including the rejection behavior for out-of-range limits and the instruction to stop when next_offset is null.

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 ('List') and resource ('alert definitions') and clarifies they are templates that generate alerts when triggered. It also distinguishes the returned ids' use from the sibling set_alert_definition_state, so the tool's role is 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 clear operational guidance: use a returned id with set_alert_definition_state, and explains pagination semantics precisely. It does not explicitly contrast with create/delete/list siblings, but the usage context is strong enough to guide selection.

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

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

Annotations already mark this read-only, but the description adds substantial behavioral detail: 404 on unknown alert id rather than empty list, the exact paginated envelope, the unusual notes_note/UNKNOWN edge case, and explicit pagination instructions. This is exactly the context an agent needs beyond the hints.

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 dense rather than padded, front-loads purpose and output shape, and then covers pagination and error cases. Some phrasing is slightly convoluted, but each sentence carries essential operational detail for a tool with no output schema.

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 paginated list tool with no output schema and several non-obvious edge cases, this description is complete: row format, pagination loop mechanics, error behavior, and the critical 'do not report UNKNOWN as no notes' rule are all covered. An agent can invoke and interpret results correctly without additional documentation.

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 the description need not restate parameter basics. It adds real value by explaining limit rejection semantics, offset usage via next_offset, and alert_id 404 behavior. The target parameter is not elaborated, but the schema already defines its default and meaning.

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 operation ('List the notes on one alert') and clearly defines the resource and row contents. It stands apart from sibling tools like get_alert or list_alerts by naming the record type and the related write tool, add_alert_note.

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 clear context: notes for one alert, with a specific alert_id, and explicitly directs recording new notes to add_alert_note. It does not enumerate when to choose this over other list/read siblings, but the single-alert scoping and sibling pointer provide adequate guidance.

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

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

The annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, and the description's '[READ]' tag aligns with them. The description adds substantial behavioral context beyond the annotations: batched resource-name resolution, null semantics ('null means unknown, not "no resource"'), the meaning of truncated, and the rejection of out-of-range limit values. No contradiction exists.

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?

Despite being long, the description is dense and efficient. It front-loads the core purpose, then covers return fields and pagination semantics without redundant statements. Every sentence contributes operational or semantic value, and the structure flows logically from summary to envelope to paging instructions.

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?

With no output schema, the description fully carries the burden of explaining the return envelope (items, returned, limit, total, truncated, hint, next_offset) and edge cases like null resource names and null totals. It also gives explicit instructions for correct pagination and warns against looping on truncated, making the tool safe and complete for an agent to use.

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 every parameter is already documented in the input schema. The description largely restates the schema's parameter semantics, such as limit's 1–500 range and offset's 'how many rows to skip', without adding significant new parameter-specific meaning. Baseline 3 is appropriate.

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 opens with '[READ] List alerts from Aria Operations', a specific verb and resource, and clearly enumerates the returned alert summaries. It is clear and unambiguous, but it does not explicitly name or differentiate any sibling tools such as get_alert or list_alert_definitions, so it stops short of a 5.

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 rich operational guidance on how to page through results—'pass it back as offset and stop when it is null' and 'Do not loop on truncated'. However, it gives no explicit when-to-use guidance or alternative routing, leaving the choice between list_alerts and sibling list/detail tools to be inferred.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, the description adds critical behavioral detail: limit bounds the answer but not the scan, the whole inventory is read in bulk pages, and scan_complete/truncated semantics reveal when results may be partial. It goes well beyond annotation coverage and explains real-world edge cases like a short list not proving a clean environment.

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?

Though lengthy, the description is tightly structured with a READ marker, context, parameter behavior, and output envelope explanation. Every sentence contributes necessary operational knowledge, and the most important purpose statement is front-loaded. The length is justified by the tool's non-obvious scan/ranking behavior.

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?

With no output schema, the description fully documents the paginated response envelope and the meaning of each field, including returned, limit, total, truncated, hint, scanned, vm_total, and scan_complete. It also covers the partial-scan caveat and explains why a short result list is not sufficient evidence of cleanliness. Nothing critical is missing for an agent to call this 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?

Schema coverage is 100%, but the description substantially enriches parameter meaning. It explains the resource_id branching behavior, clarifies that limit is a result bound rather than a scan bound, and notes that out-of-range limits are rejected. This adds genuine semantic value beyond the schema's already-good 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?

Description states a precise verb and resource: 'Report per-resource anomaly counts' via the Total Anomalies metric. It clearly distinguishes itself from the UI's anomalous-metrics list and from list_alerts, which is for root cause follow-up. An agent can tell exactly what this tool computes.

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 mode-based guidance: with resource_id it returns that resource's count, without it ranks all VMs and returns the worst limit. It also names list_alerts as the follow-up tool for root cause, providing an alternative routing decision. This is strong, actionable usage guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: it discloses the pagination envelope fields, notes that total is null when the API reports no size, warns to check truncated, and explains the enrichment via one extra collectors call. No contradictions with 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 well-structured and front-loaded: purpose, context, usage trigger, behavioral caveats, and return format. Every sentence adds value, and the pagination warning is placed at the end without clutter.

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?

The tool is simple (one optional parameter, no required inputs, no output schema), but the description still covers the key operational concerns: when to use it, what groups contain, what a DOWN collector implies, and what the paginated response looks like. Nothing essential is missing.

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?

The schema already fully covers the single parameter with a clear description: 'Aria target name from config; default when omitted.' Since schema description coverage is 100%, the description doesn't need to add parameter details. It adds no new parameter semantics but is not deficient.

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 opens with a specific verb and resource: 'List Aria Operations collector groups and their member collector status.' It also explains what collectors are and links the tool to symptoms (missing/stale resources), making its purpose distinct from siblings like list_resources and get_resource_metrics.

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 explicitly says when to use this tool: 'Check this when resources appear missing from Aria Operations or metrics are stale.' It also explains how a DOWN collector affects list_resources and metric tools, which is a clear usage signal. It doesn't name alternatives to rule out, but the context is sufficiently clear.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses non-obvious behavior: the schedules_note semantics where items is UNKNOWN and must not be reported as 'no schedules', the rejection (not clamping) of out-of-range limit values, and the requirement not to loop on truncated. These are exactly the edge cases an agent needs to invoke and interpret the tool correctly.

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 and front-loaded with the core listing purpose, followed by a caveat, a sibling mention, and pagination guidance. It is somewhat long, but with no output schema, the detailed envelope and pagination rules earn their place. Minor redundancy remains, but nothing is wasted.

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 lack of an output schema, the description is unusually complete: it covers the return envelope, pagination mechanics, resource filtering, an important edge case about UNKNOWN items, and routes to the relevant sibling tool. An agent has everything needed to call and iterate this tool 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?

Schema coverage is 100%, so the baseline is 3, but the description adds valuable operational semantics: resource_id filters to only schedules for one resource, next_offset should be passed back as offset and iteration stops when it is null, and limit out-of-range values are rejected rather than clamped. This goes beyond the schema 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 states a specific verb ('List') and resource ('recurring maintenance schedules') and enumerates the exact returned fields (name, schedule type, recurrence, start hour/minute, duration, time zone, start, and expiry). It also distinguishes itself from start_resource_maintenance by saying the latter is for putting a resource in maintenance now, so an agent can tell them apart.

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 explicitly tells when to pass resource_id and names the alternative for immediate maintenance ('To put a resource in maintenance now, use start_resource_maintenance'). It also provides clear pagination instructions, including when to stop using next_offset, so the usage context is fully specified.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavior beyond that: per-resource vs per-kind key semantics, possible definition statuses (found, found_by_instance, not_defined_for_kind, not_read), pagination envelope behavior, and the non-obvious rule that an unreadable key list is an error, never empty. No contradiction with 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 dense but every sentence earns its place: lookup purpose, per-mode semantics, pagination, and error behavior. It is front-loaded with the most important instruction and uses clear paragraph breaks to separate modes and operational details without padding.

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?

With no output schema, the description does a strong job of explaining return semantics (statuses, units, pagination envelope) and failure behavior. The only small gap is the unexplained 'see unjoined_keys' referenceressing without an output schema or sibling tool with that name, leaving a minor ambiguity for an agent.

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 100%, so the baseline is 3 degrees, but the description adds real value for resource_id and resource_kind by explaining what their results mean ('keys that resource reports' vs 'keys the kind defines') and the definition statuses. Other parameters like target, key_filter, and adapter_kind are already well-described in the schema and need no extra explanation.

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 opens with a specific verb and resource: 'Look up metric keys before get_resource_metrics or get_top_consumers.' It also clarifies the scope with a concrete example of what not to guess ('cpu|demand_average does not exist on VMs'), making the tool's purpose and boundary 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?

It explicitly tells the agent when to use this tool: before calling get_resource_metrics or get_top_consumers, and never to guess keys. It also distinguishes the two usage modes, resource_id and resource_kind, and gives pagination instructions ('pass it back as offset until null'), which is direct actionable guidance.

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

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

The description discloses important runtime behavior beyond the annotations: the exact pagination envelope shape, that truncated indicates page incompleteness and stays true on the last page, that limit values are rejected rather than clamped, and that total can be null. This gives an agent accurate expectations without invoking the tool.

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 organized into three focused paragraphs: purpose/workflow, return envelope, and pagination walk. Every sentence adds essential information about a non-trivial paginated endpoint. No filler or repetition.

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?

With no output schema, the description fully compensates by documenting the response envelope, null total, truncated flag, and next_offset semantics. It also covers the key edge cases (limit rejection, stop condition, don't loop on truncated). The tool is complex, and the description is complete enough for correct invocation and response interpretation.

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 100%, so the baseline is 3. The description enriches the meaning of limit and offset by explaining the rejection behavior, the skip semantics, and the next_offset handshake. It does not add detail about name_filter or target, but those are already well-described in the schema, so the additional value warrants a 4.

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 verb ('List') and resource ('available report definition templates in Aria Operations'), and distinguishes the tool from the sibling generate_report by stating that returned ids are passed to it. The term 'definition templates' also differentiates it from list_reports, which presumably lists generated reports.

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 explains the intended workflow: list definitions, then pass an id to generate_report. It also provides detailed pagination usage instructions, including how to use next_offset and when to stop. It does not explicitly state 'use this instead of list_reports', but the workflow context makes the primary use case clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavior: the paginated envelope shape, total possibly null, the meaning of truncated, and the critical caveat that there is no offset so truncated pages cannot be walked past. This is exactly the kind of non-obvious behavior an agent needs to know.

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 front-loaded with purpose and the get_report routing, then packs the essential pagination behavior into a second dense but efficient paragraph. Every sentence adds meaningful information with no filler.

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?

With no output schema, the description fully compensates by enumerating the response envelope fields and the truncation semantics. It also covers the tool's relationship to get_report and the optional filter, leaving no critical gap for an agent to call this tool 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?

Schema description coverage is 100%, so the burden on the description is low. The description adds a little context by mentioning filtering by report definition, which maps to definition_id, but it does not explain limit bounds or target beyond what the schema already provides.

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 opens with a precise verb and resource, 'List generated reports', and immediately states the optional filter by report definition. It also differentiates the tool from its sibling get_report by directing readers to use that tool for status and download URLs, making the boundary clear.

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 clear routing guidance, explicitly telling the agent to pass a returned id to get_report for status and download URLs. It also implies when definition_id should be used, but it does not explicitly contrast with list_report_definitions or mention when not to use this tool.

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

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

Adds substantial behavior beyond the annotations: clarifies that aria_state is a lifecycle state, not a power state; explains collection_status semantics; notes the status alias; details the paginated envelope; and warns to check truncated. No contradiction with 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?

Well-structured and front-loaded with [READ] and the core purpose. The longer sections on row fields and return envelope earn their place because there is no output schema to carry that information otherwise.

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?

Complete for a read-only list tool: the description details the return envelope, pagination behavior, caveats around null total, and special note behavior. Combined with the annotations and full schema coverage, an agent has everything needed to call it 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?

Schema coverage is 100%, so the schema already documents all five parameters. The description adds some context around filtering and output caveats, but it does not significantly enrich the meaning of individual parameters 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?

States a specific action ('List resources in Aria Operations filtered by kind') and a clear purpose: translating a name or kind into the UUID that other resource tools require. It distinguishes itself from get_resource by describing the list-to-detail workflow.

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?

Gives explicit workflow guidance: 'Start here' to resolve a UUID, then 'call get_resource for detail on one row.' This clearly establishes context for use, though it does not explicitly enumerate exclusions such as 'skip this if you already have the UUID.'

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description goes far beyond that: it discloses that powered-off VMs and templates are included, product_name is unreliable for vendor appliances, recommendation_stable can be null, history reads can fail and null out fields, and that properties_note appears only on partial read failures. It also warns that the API result will not match the vendor UI number. This is exemplary disclosure of behavioral edge cases.

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 very long, but the length is justified by the absence of an output schema and the many genuine pitfalls (null semantics, unit conversions, pagination, vendor caveats). It is front-loaded with a clear purpose statement and then systematically addresses interpretation, units, edge cases, and return-envelope fields. It is not concise in absolute terms, but every major section earns its place given the complexity.

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?

With no output schema, the description carries full responsibility for explaining the response envelope: items, returned, limit, total, truncated, hint, properties_note, history_note. It explains null semantics for total, properties_note, history_note, recommendation_range, and recommendation_stableedited. It covers units, direction values, actionable criteria, and vendor caveats. An agent has enough context to call the tool and correctly interpret almost every field without external documentation.

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?

Input schema description coverage is 100%, so the schema already documents limit, target, and resource_id with defaults and meanings. The description adds minor context, such as using list_resources for VM UUIDs and 'one bulk stats call and one bulk properties call cover the whole page,' but it does not add significant semantic meaning beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 first sentence states a specific verb and resource: 'List VM rightsizing data — recommended CPU/memory/disk size per VM, with units, direction and whether to act.' It further differentiates the tool by noting it reads the only three rightsizing metrics the public API publishes, and explicitly contrasts its output with the vendor UI's Rightsize page. This clearly distinguishes it from sibling alert, anomaly, and capacity 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?

The description gives extensive procedural guidance: read sizing_status before quoting numbers, never treat reclaimable 0 as a zero-size recommendation, check power_state/is_template/actionable, read caveats, and consult recommendation_stable before acting. It also tells the caller to get VM UUIDs from list_resources. However, it does not explicitly name alternative sibling tools or state when this tool should be preferred over them; the guidance is mostly internal to this tool's output interpretation rather than cross-tool routing.

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

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

Annotations already signal readOnlyHint and idempotentHint, but the description adds substantial non-obvious behavior: the exact paginated envelope fields, the meaning of truncated, the 'rejected, not clamped' limit handling, and the explicit warning not to loop on truncated. This goes well beyond what annotations provide.

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 purpose is front-loaded, and every subsequent sentence explains a nontrivial behavior needed to invoke the tool correctly. The pagination instructions are dense but not padded, and the warning about truncated earns its place.

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 paginated list tool with 5 optional parameters and no output schema, the description covers the return envelope, the pagination contract, and the edge-case caveat about truncated. It tells the agent what it will receive and how to iterate safely, so nothing critical is missing for correct invocation.

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 100%, so the baseline is 3. The description adds extra value by explaining how limit, offset, and next_offset interact: pages are walked by passing next_offset back, out-of-range limits are rejected, and next_offset being null signals the end. This clarifies parameter behavior beyond the schema 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 opens with '[READ] List symptom definitions' and ties the tool to a concrete downstream use: 'use the returned IDs when calling create_alert_definition.' This clearly identifies the verb, resource, and purpose, and distinguishes it from sibling tools like list_alert_definitions.

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?

It gives a clear use case for the tool by relating its IDs to create_alert_definition, and its read-only nature is reinforced. It does not explicitly compare against sibling tools like list_alert_definitions, but the purpose statement is enough to orient an agent without leaving the main scenario ambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description discloses a real-time latency profile, a hard prerequisite (VODAP integration) with the resulting actionable error, and the return envelope contents. It also surfaces a non-obvious gotcha: the sibling service base path is inferred and every result carries base_path_confirmed=False until validated. This is substantial behavioral context.

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 compact yet information-dense, with each sentence contributing a distinct fact: purpose, use case, prerequisite, return format, and a critical gotcha. The '[READ]' prefix and front-loaded purpose statement make the tool's intent immediately clear.

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 read-only query tool with full schema coverage and no output schema, the description covers the essential operational context: when to use it, what it returns, the required integration, error behavior, and a latency caveat. An agent has enough information to select and invoke it correctly under normal conditions.

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 the input schema and its per-property descriptions already document all five parameters thoroughly. The description adds high-level context about the query and return shape, but does not need to repeat parameter syntax; baseline 3 is appropriate.

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 opening line, '[READ] Run a real-time PromQL instant query', states a specific verb, resource, and temporal characteristic. It also names the underlying VODAP service, separating it clearly from the historical-rollup tool get_resource_metrics among the siblings.

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 explicitly says to use this for near-real-time (~2s) metrics and references get_resource_metrics as the complementary historical alternative, giving clear context for tool selection. It does not spell out an explicit 'do not use when...' condition, though the complementing-rollups phrase implies the boundary.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavioral context: it labels the operation as [WRITE], explains that disabling is reversible while deleting is not, and states the return fields (definition_id, enabled, action taken). This goes beyond the annotations without contradicting them.

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 two sentences with no redundancy. The [WRITE] marker and primary action are front-loaded, and the alternative guidance is compact and directly actionable. Every sentence earns its place.

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 simple mutation tool with all parameters schema-documented and no output schema, the description covers the essential context: what it does, when to use it, what it returns, and how it differs from the destructive sibling. An agent has enough to select and call this tool 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of semantic context by equating disabling with 'silencing' a definition, but it does not materially explain any parameter beyond what the schema already provides (definition_id from list_alert_definitions, enabled True/False).

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 a specific verb ('Enable or disable') and a specific resource ('an existing alert definition'), distinguishing it from sibling tools like delete_alert_definition and create_alert_definition. It leaves no ambiguity about what action the tool performs.

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?

It explicitly gives the condition for choosing this tool over delete_alert_definition: 'Use this instead of delete_alert_definition when you only want to silence a definition'. It also explains the rationale (reversible vs. irreversible), providing clear when-to-use guidance.

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

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

Annotations only signal readOnly/destructive/idempotent hints, so the description carries the burden — and it delivers: preview-vs-execute behavior, full return semantics ("confirmed (true / false / null when the after-state could not be read — null is unknown, not failure)"), state transitions ("the resource returns to its prior state when it expires"), and the undo edge case ("recorded only when the resource was known not to be in maintenance before"). The [WRITE] prefix aligns with readOnlyHint=false and the revert-on-expiry behavior aligns with destructiveHint=false; no contradiction.

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 purpose is front-loaded and every sentence earns its place — there is no filler or repetition. However, ~120 words of dense prose covering three modes, return fields, preview semantics, and undo edge cases arrive as a single unbroken block; light segmentation would improve parseability. Efficient, but slightly over-packed.

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?

With no output schema, the description fully compensates by explaining the return payload (before/after states, confirmed semantics, note). All three parameter modes, the default preview behavior, the undo path via the named sibling, and the human-factors risk ("easy to forget, so prefer a window") are covered — nothing an agent needs to invoke this tool correctly or safely is missing.

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 100% and the schema already documents mutual exclusion, the confirmed preview flag, the epoch-milliseconds unit, and the 1-525600 range, so the baseline is 3. The description adds genuine value by mapping parameter combinations to resulting states — timed window yields MAINTAINED with auto-return, omitting both yields MAINTAINED_MANUAL that persists — which is a mental model absent from the schema. The increment is real but modest given the schema's own thoroughness.

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 opening clause "Put one resource in maintenance so Aria stops alerting on it and collecting its data" states a specific verb, the resource acted on, and the observable effect, going beyond a generic phrase like 'start maintenance.' The concrete scenario "use before planned work such as powering a VM or host off" grounds it, and the named states (MAINTAINED vs MAINTAINED_MANUAL) implicitly distinguish it from the paired sibling end_resource_maintenance.

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 an explicit when-to-use rule ("use before planned work such as powering a VM or host off") and prescriptive parameter selection: "Pass duration_minutes OR end_time_ms... Pass neither for manual maintenance" with a clear recommendation ("easy to forget, so prefer a window"). It names the alternative tool outright ("Undo: end_resource_maintenance") and discloses the safe preview path ("Default confirmed=False returns a preview without connecting"), leaving nothing to inference.

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