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

With no annotations, the description carries the full burden and does disclose meaningful traits: full write/delete capability (destructive methods named), and the non-obvious output transformation that inventory lists are flattened into 'items' unless raw=true. Auth requirements, rate limits, and error behavior are not mentioned, so it is not complete, but the response-shaping disclosure is real value beyond the 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?

Two dense sentences with zero filler; the endpoint/method scope and identification mechanism are front-loaded, and the output-shaping caveat follows immediately. Every clause carries information an agent needs.

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 12-parameter generic passthrough with no output schema and no annotations, the description covers the essentials: what it reaches, how to target it, and how the body is shaped. It stops short of the surrounding context an agent would want (auth prerequisites, error/validation behavior, relationship to the dedicated workflow/action tools), leaving a modest gap given the tool's complexity.

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 50%, so the description must compensate, and it does for the central parameters: it explains operationId (preferred, sourced from vro_api_search), method+path relative to /vco/api, and the raw flag's effect on flattening. Several parameters (maxChars, includeHeaders, contentType, headers, body) remain undocumented in both schema and description, which keeps it short of a 5.

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 ('Call any Orchestrator REST endpoint'), enumerates the full method scope (GET/POST/PUT/PATCH/DELETE), and explicitly routes discovery to the sibling vro_api_search for operationId. An agent can distinguish this generic passthrough from the dedicated siblings 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 a clear preference rule for identifying the endpoint (operationId preferred, sourced from vro_api_search, else method+path), which is genuine usage guidance. However, it never says when to prefer the dedicated siblings (vro_run_workflow, vro_get_workflow, vro_find_workflows, etc.) over this generic caller, nor when this tool is the wrong choice. Usage is implied rather than bounded.

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 readOnlyHint=true already declaring the safety profile, the description adds real value: it discloses that $refs are resolved in the returned body schema and specifies the success-response coverage. It stops short of stating anything about failure modes (e.g., unknown operationId) or how large a resolved schema may be.

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 sentences, zero filler. The output enumeration comes first and the routing instruction second, which is the right front-loading for a lookup tool.

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?

No output schema exists, so the description must carry the return-value burden, and it does: it names the parameter categories, the resolved body schema, and the success response shape. The only omission is the provenance of operationId, which an agent must infer from the sibling search tool.

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 50%: depth is documented inline ('How deep to inline nested schemas (default 3)') while operationId has no schema description. The description indirectly supports depth by advertising $refs resolution, but never explains where an operationId comes from (presumably vro_api_search), so it only partially compensates for the gap.

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?

Specific verb ('Show') plus specific resource ('one Orchestrator API operation in detail'), with an enumeration of exactly what is returned: path/query/header parameters, request body schema with $refs resolved, and success response shape. An agent can distinguish this from the sibling vro_api_search (find operations) and vro_api_call (invoke them) without opening any 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?

Explicitly routes usage: 'Use before vro_api_call for anything with a body,' naming both the alternative tool and the selecting condition. No explicit when-not is given (e.g., that a bodyless GET needs no describe step), so it falls just short of the full when/when-not/alternatives bar.

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 declare readOnlyHint=true, so safety is covered. The description adds useful context: the spec size (300+ operations), the return type (operationIds), and the special empty-query mode. It does not mention result limits/caps or ranking behavior, which matters for a search 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?

Three tightly-packed sentences: purpose, outputs/next-step, and a discovery tip. Front-loaded and no filler, though the example list is slightly dense in one sentence.

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?

No output schema, but the description states what comes back (operationIds) and how to use them, which is what matters for a discovery tool. Missing: result-count behavior and how tag/method filters interact.

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 60%, so the description must partially compensate. It explains the empty-query/listTags idiom and names concrete query shapes ('workflow execution logs', '/packages'), going beyond the schema for the two parameters an agent most needs to understand. It does not clarify tag/method/limit 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?

States a specific verb (Search) and resource (Orchestrator REST API spec) with concrete example queries, and explicitly names the sibling tools (vro_api_describe / vro_api_call) that consume its output. An agent can distinguish it from every sibling in the list.

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?

Clearly situates this as the discovery step before vro_api_describe/vro_api_call, and gives the query='' + listTags=true idiom for browsing API areas. It lacks explicit when-not-to-use guidance (e.g., when to prefer the higher-level workflow tools like vro_find_workflows).

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 destructiveHint=true annotation already tells the agent this is a destructive operation, lowering the disclosure bar. The description usefully adds that the workflow may be resolved by an exact name rather than only an id, but says nothing about whether deletion is permanent, what dependencies or versions are affected, or what permissions are needed, and the boolean 'force' behavior is entirely undisclosed.

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?

A single tight sentence with the operation and identifier semantics front-loaded and no filler. It is arguably over-terse for a destructive tool, 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?

For a destructive, irreversible-sounding delete with an undocumented 'force' flag, no output schema, and only a destructiveHint annotation, the description omits permanence, dependency/version side effects, and auth requirements. An agent has enough to attempt the call but not enough to judge the consequences.

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?

With 0% schema description coverage, the description carries the burden, and it does clarify the required 'workflow' parameter (id or exact name), which is more than the schema states. However, the 'force' boolean is left completely unexplained in both schema and description, so the compensation is only partial.

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 and resource ('Delete a workflow'), which clearly separates it from read-oriented siblings like vro_get_workflow and write siblings like vro_save_workflow. It adds a resolvable-identifier clause ('by id or exact name'), though it never references a sibling by name to route the agent explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus alternatives such as vro_save_workflow (which can overwrite) or vro_find_workflows (to locate a target first), and no mention of prerequisites or irreversibility. The agent must infer usage entirely from the name.

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 readOnlyHint annotation already establishes this is a safe, non-mutating lookup, so the description's burden is lower. It adds useful return-shape information (fqn module/name and id) but says nothing about result ordering, truncation, or how limit interacts with results.

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 tight sentences, front-loaded with the action and its matching semantics, followed by the return fields. No filler; only the bare return clause is slightly clipped.

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 must carry return-value context; it names the returned fields but not the surrounding structure (list, ordering, whether matches are exhaustive within limit). Adequate for a simple search tool, but incomplete on result behavior.

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 0%, so the description must compensate. It explains the semantics of 'query' (partial module or name match) with examples, which is genuinely helpful, but 'limit' is completely undocumented in both schema and description, leaving half the parameters opaque.

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?

Specific verb+resource: 'Find Orchestrator actions by partial module or name', with concrete query examples ('getAllVMs', 'com.vmware.library.vc'). It is clear this is the search/fuzzy-match entry point, but it does not explicitly distinguish itself from siblings like vro_get_action or vro_api_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus alternatives such as vro_get_action or vro_api_search. The phrase 'by partial module or name' implies fuzzy lookup, but the agent must infer that this is the discovery step preceding get/run calls.

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 readOnlyHint=true annotation already establishes this is a safe, non-mutating read, so the description's burden is reduced. It adds the enumerated return fields (id, name, category, version, description), which is genuine value, but says nothing about result volume, paging behavior, or case sensitivity of the partial match.

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 tight sentences with zero filler, front-loading the action and match mode before the return payload. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, listing the returned fields is a necessary and well-used addition, and the search semantics are clear. But for a paginated lookup tool, the absence of any paging or result-size guidance leaves the definition adequate rather than 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 description coverage is only 33%: 'name' is documented ('Partial name; omit to list all') but 'limit' and 'startIndex' have no descriptions at all. The tool description does nothing to compensate, never explaining paging, the 500 cap, or how startIndex interacts with limit, leaving two of three parameters semantically opaque.

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 and resource ('Find Orchestrator workflows') plus the matching mode ('by (partial) name'), which distinguishes it from the id-based sibling vro_get_workflow. It does not, however, mention the near-twin vro_find_actions or explicitly contrast search vs. get, so sibling differentiation is only implied.

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?

Usage is only implied: the word 'Find' plus 'partial name' suggests this is the discovery/lookup entry point before using vro_get_workflow or vro_run_workflow, but the description never states when to prefer it over those siblings or what prerequisites apply. No exclusions or alternative routing are provided.

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 supply readOnlyHint=true, so the safety profile is covered; the description adds only the returned fields (script, inputs, return type), which is useful but thin. It says nothing about whether unknown references error out, scoping/permissions, or payload size.

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 short, front-loaded sentences with no filler. Terse to the point of omitting needed detail, but nothing is wasted or buried.

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 at least names the returned fields, and annotations cover safety, so this is minimally viable. But for a lookup tool with an undocumented parameter and no error behavior described, an agent is left guessing on edge 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 0%, so the description carries the full burden, and it only partially does so: it gives the accepted reference formats 'module/name' or id. It does not clarify whether id is a UUID or numeric, case sensitivity, or what happens on a missing action.

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 (Get) and resource (an action), and enumerates what is returned: script, inputs, return type. It is distinguishable from vro_run_action and vro_find_actions, but does not explicitly name a sibling to differentiate from, holding it at 4 rather than 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?

No guidance on when to call this versus vro_find_actions (to locate actions) or vro_run_action (to execute one). The implicit reading is 'use this when you already know the action identity,' but that is never stated, and no exclusions or prerequisites are given.

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, so the safety profile is covered. The description adds some behavioral context by mentioning optional logs and the ability to wait for completion, but it does not describe limits on waiting, log volume, or behavior when the execution is already finished.

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 compact sentences and is front-loaded with the core action. Every sentence contributes useful information without 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 read-only get tool with no output schema, the description does explain what is returned at a high level. However, with five parameters and only 20% schema description coverage, it leaves too much parameter detail and usage guidance unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20%, and the description only loosely covers includeLogs and waitSeconds. It does not explain workflowId, executionId, or includeInputs, leaving most parameters semantically undocumented beyond their names.

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 gives a specific verb and resource: get a workflow execution, returning state, outputs, error, and optionally logs. It also states that it can wait for completion. However, it does not explicitly differentiate itself from siblings like list_executions or run_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?

The description implies usage for inspecting a specific execution and notes the optional wait behavior, which is a useful scenario cue. But it does not say when to use this tool versus list_executions or other execution-related siblings, and it gives no exclusions or prerequisites.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description carries less burden. It adds that the lookup is exact-match and that returned data includes typed inputs/outputs, but says nothing about failure modes when the name is ambiguous or not found, nor about the large-payload risk that the schema mentions for includeContent.

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?

A single sentence that front-loads the verb and resource, then the payload fields, then the lookup key. 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?

With no output schema, the description usefully enumerates what comes back and how identifiers are resolved, and annotations cover the safety profile. Only minor gaps remain, such as behavior on ambiguous/missing names or the exclusion of full content by default.

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 documented in the schema, establishing a baseline of 3. The description only reinforces that 'workflow' accepts an id or exact name and says nothing extra about includeContent beyond what the schema states.

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 ('Get'), resource ('a workflow'), and enumerates the returned fields (inputs/outputs names + types, version, description). This clearly separates it from vro_find_workflows (search) and vro_save_workflow (mutation).

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 phrase 'by id or exact name' signals this is a precise-identifier lookup rather than a search, which implicitly routes agents away from vro_find_workflows. However, it never names the alternative or states an exclusion explicitly, so usage context is clear but not fully prescriptive.

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?

readOnlyHint=true already tells the agent this is a safe read operation. The description adds useful return-field context (id, state, start/end, started by), which matters since no output schema exists, but it does not define 'recent', the default limit, or pagination behavior.

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?

A single front-loaded sentence with the verb and resource first and the returned fields in parentheses. No wasted words, though it is terse to the point of omitting operational detail.

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 annotations covering safety, the core purpose is conveyed. However, 'recent' is undefined, no default or maximum for limit is given, and there is no hint about how the state filter interacts with the results, which leaves real gaps for a filtering list operation.

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 67%, and the description's parenthetical lists returned fields rather than inputs, so it adds no meaning for the three parameters. The 'limit' parameter has no schema description and no compensating explanation in the description, leaving the agent to guess its default and cap.

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 (executions of a workflow), so the agent knows it retrieves execution history rather than running or fetching a single execution. It does not explicitly distinguish itself from the singular sibling vro_get_execution, but the intent 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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives such as vro_get_execution for a single run or vro_run_workflow to start one. The agent must infer the list-vs-get distinction from the name alone.

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 no annotations, the description carries the burden but does disclose meaningful behavior: synchronous execution, plain-JSON input coercion, plain-JSON result conversion, error reporting with line number, and logs. It stops short of stating permission requirements or side effects of the executed action.

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?

A single front-loaded sentence with no filler, packing execution mode, input format, and return shape efficiently. Dense but not padded.

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?

No output schema exists, so the description usefully describes the return payload (result, error with line number, logs). It is largely complete for a run tool, with the main gap being the absence of usage routing against sibling execution tools.

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 50%: 'action' is documented in the schema ('module/name' or action id), while 'inputs' is not. The description compensates by specifying the inputs shape ({inputName: value}), adding real meaning for the undocumented parameter, but says nothing about resolving the action identifier.

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 (Execute) and resource (action), and notes synchronous execution. It implicitly distinguishes itself from the sibling execution tools (vro_run_workflow, vro_run_script) by naming 'action', though it never explicitly contrasts them.

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 notes it runs synchronously but gives no guidance on when to choose this over vro_run_workflow, vro_run_script, or the async/execution-based tools. An agent must infer the selection criteria from the name alone.

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?

No annotations are provided, so the description carries the full burden. It discloses the temporary-action lifecycle, return value plus System.log output, and the ES5/Rhino script constraints, but omits permissions, rate limits, and potential side effects of executing arbitrary code.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose and usage, then behavior, then constraints. Every sentence earns its place; no redundant or vague wording.

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 absence of an output schema, the description explains the return value and System.log output. It also covers script language constraints and the temporary action lifecycle, making it largely complete, though it could mention error handling or required permissions for a code-execution tool.

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 five parameters. The description adds only that inputs are 'available as variables' inside the script, which is marginal beyond the schema's own 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?

States a specific verb and resource: run an ad-hoc JavaScript snippet on Orchestrator. It distinguishes itself from saved-action siblings by noting the temporary action lifecycle ('creates a temporary action ... then deletes the action'), though it does not name an alternative sibling explicitly.

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 clear usage context: 'for prototyping and quick checks.' However, it does not state when not to use it or name alternative tools (e.g., vro_run_action) for production or repeatable tasks.

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 no annotations, the description carries the behavioral burden and does so well: it discloses automatic type conversion, the default blocking/wait behavior, and what is returned (state, outputs, error, logs). It omits auth/permission requirements and side-effect details, but the execution semantics are unusually well covered.

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?

A single dense sentence that front-loads the core action before the parenthetical detail on type conversion and the trailing note on default wait behavior. Every clause earns its place, though the density is slightly heavy for one sentence.

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 annotations and no output schema, the description compensates by describing return contents and default timing, and it covers the otherwise-undocumented inputs parameter. Missing only edge-case/error and permission context, so it is close to complete for calling the 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 80% (only 'inputs' is undocumented in the schema), and the description fills that gap precisely by explaining the {inputName: value} shape and the automatic conversion of values to Orchestrator types. This adds real meaning beyond the structured fields.

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 ('Run a workflow') and how it is identified (by id or name), which separates it from run_action and run_script siblings by resource type. It does not explicitly name those siblings, so it stops short of full differentiation.

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?

Usage is implied by the verb and the 'by default waits' behavior, but there is no explicit when-to-use guidance nor any mention of alternatives like vro_run_action or when wait=false is preferable. A reader can infer intent but gets no routing help.

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 no annotations, the description carries the full burden and does so well: it discloses the ES5/Rhino runtime constraint, that omitted inputs/returnType are preserved on update, and the versioning policy (new = 1.0.0, patch bump unless version/bump given). It does not cover permissions, atomicity, or what the call returns, so not a 5.

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 tight sentences, each with a distinct payload (purpose, script constraint, update merge, versioning), and the primary create/update intent is front-loaded. Parenthetical examples are compact and useful.

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 an 8-parameter mutation with no annotations and no output schema, the description covers the operational essentials an agent needs (upsert key, script dialect, merge behavior, versioning). It leaves out permission requirements and the failure/return shape, which would be nice but are secondary.

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 only 50%, so description additions matter: it constrains script to plain ES5 (a real correctness rule absent from the schema) and clarifies preservation semantics for inputs/returnType plus version/bump behavior. It does not resolve module/name formats beyond 'upsert by module/name', but that plus the schema examples is adequate.

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 (create/update, i.e. upsert) and resource (action), with the keying scheme (module/name) that defines identity. It is clearly distinguishable from siblings like vro_get_action and vro_run_action.

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 implies when it applies (new action vs update, keyed on module/name) and notes update-time merge behavior, but names no alternatives or when-not conditions. An agent must infer that vro_get_action/delete workflows are the other routes. Implied usage only.

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 no annotations, the description carries the full burden and does well: it discloses side effects (builds schema, creates missing folder path, validates), an ES5 scripting constraint, control-flow defaults (array order unless next/ifTrue/ifFalse), and a versioning policy (new = 1.0.0, patch bump on update unless version/bump given). It omits auth/permission needs and what happens on validation failure or when overwriting an existing workflow.

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?

Dense but front-loaded: the upsert purpose and spec come first, then side effects, then the scripting constraint, versioning, and dryRun. Sentences are information-bearing, though the version-bump rule is stated twice (in prose and implied again in the schema) and the block is on the long side.

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 10-parameter nested-spec tool with no output schema and no annotations, the description covers the authoring model, control flow, versioning, and dryRun preview well enough to call it correctly. Remaining gaps are return-shape specifics (workflow id, resulting version, validation errors) and permission requirements, which are not addressed.

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 only 30% across 10 parameters, so the description must compensate, and it does for the highest-value ones: dryRun's preview-only XML behavior, the version/bump interaction, step ordering and next/ifTrue/ifFalse routing, and the inputs/outputs/attributes spec. It adds real meaning beyond the schema, though args/action linking and resultTo are left entirely to 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 verb (upsert/create-or-update) and resource (Orchestrator workflow) plus the keying rule (name + folder) and the spec it consumes. It is distinguishable from sibling save/find tools like vro_save_action and vro_get_workflow without opening any 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?

The create-vs-update behavior is implied by 'upsert by name + folder' and dryRun gives a preview path, but there is no explicit when-to-use guidance, no prerequisites (e.g. whether an existing workflow should be fetched first), and no named alternatives such as vro_save_action. Usage is inferable rather than stated.

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 only readOnlyHint declared, the description adds real behavioral context: it performs a login, and it reports the server's about info, auth mode, and loaded spec. The 'logs in' detail is worth disclosing since a session handshake is more than a pure read, though it is not destructive enough to contradict readOnlyHint.

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 short sentences: the first front-loads what the tool does and returns, the second delivers the single most actionable instruction ('call this first if anything fails'). 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?

No output schema exists, so the description compensates by naming the returned payload (about info, auth mode, API spec), and there are no parameters to document. An agent has everything needed to decide to call it and interpret the result.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. It correctly avoids inventing input 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?

States a specific verb ('Check connectivity') plus resource ('VCF Operations Orchestrator') and enumerates exactly what is returned: /about info, auth mode, loaded API spec. This is clearly distinguishable from every sibling (api_search, find_workflows, run_workflow, etc.), none of which is a connectivity/diagnostic probe.

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 routing guidance: 'Call this first if anything fails,' which tells the agent exactly when to reach for it. It stops short of naming an alternative or a when-not condition, so it falls just under the top band.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that it acts in bulk over whole modules or listed fqns/ids and does not alter content, but says nothing about reversibility, permissions, version-history semantics, or error behavior when a target is missing or the version conflicts.

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 tightly written sentences; the operation and its scoping constraint are front-loaded and the use case follows. 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 6-parameter mutation tool with no annotations and no output schema, the description covers the 'what' and 'why' well but omits operational detail an agent would want, such as conflict behavior, whether prior versions are retained, and what a partial failure across a module returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already documented. The description mostly restates the schema's set-vs-bump semantics ('set 1.0.0' / 'bump minor/major') and adds little beyond it, so the baseline 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?

States a precise verb (set/bump) and resource (action and workflow versions) plus the key scoping fact 'without touching their content'. That last clause implicitly separates it from the save/run siblings, so an agent can identify it 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?

Gives concrete when-to-use guidance: baselining versions (e.g. set 1.0.0) versus marking a release (bump minor/major). It does not name alternatives or state when not to use it (e.g. versus save_action), so it falls short of a 5.

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