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

The description discloses that the tool logs every POST/PATCH/PUT/DELETE and includes target, path, status, and redacted body, going beyond the annotation hints. It also notes that logs include changes from previous sessions, adding useful 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 two sentences, front-loaded with the primary purpose, followed by a concise explanation of the log contents and typical use case. No filler or unnecessary 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 simple read-only tool with strong annotations and one self-explanatory parameter, the description covers purpose, output contents, and intended usage. It lists the log fields, so no separate output schema is needed.

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 includes a single 'limit' parameter (default 50) but the description does not explain its meaning or effect. Since schema description coverage is 0%, the description should have compensated but does not, leaving parameter semantics implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Show recent mutating calls made through this server.' It identifies the action (show) and resource (recent mutation logs), and it is distinct from sibling tools by focusing on audit history rather than current state.

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 an explicit use case ('Use it to answer "what did I change?"') and notes it covers changes from earlier sessions. It does not explicitly exclude alternatives like vcf_inventory, but the context is clear enough for an agent to choose this tool for audit queries.

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?

It goes far beyond annotations by noting authentication is handled, mutating operations change the estate and some are irreversible, every mutation is audit-logged, and long-running calls return HTTP 202 + task id. This is exactly the type of behavioral context raw API callers 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 structured as a summary line, safety/async warnings, then a concise Args list. Each sentence adds unique value, and the high-risk nature of the tool justifies the 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 covers dangerous side effects, auth, async task handling, path construction, and response-size truncation. However, it does not describe the general response envelope (status/body) or error behavior beyond 202, leaving some ambiguity for a raw API caller without an output 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?

With 0% schema coverage, the description fully compensates by explaining the role of each of the 7 parameters, including exact path format with examples, query/body types, timeout default, and max_response_chars. Every parameter is given operational 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?

The description opens with 'Call a VCF API operation,' a specific verb+resource statement, and distinguishes itself from siblings by explaining how target/path come from vcf_targets/vcf_search_api and how vcf_task handles long-running results. It is unambiguous that this is the raw arbitrary API execution tool.

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 instructs to check vcf_describe_api first when writing, and to follow HTTP 202 responses with vcf_task rather than assuming success. It also situates the tool among siblings by sourcing target from vcf_targets and path from vcf_search_api, giving clear when/how 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 readOnlyHint=true and idempotentHint=true, and the description adds context by explaining what the tool returns (path/query parameters, request body schema with required fields, response schemas) and how depth/max_properties affect the output. It also warns that 'VCF request bodies are large and unforgiving', which is useful behavioral context. 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 concise and well-structured: a clear opening, a usage note, and a compact Args section. Every sentence adds value, with no redundant or filler content. The formatting with bullet-like Args makes scanning easy.

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, the description provides adequate information about return values (schemas, required fields, response schemas). It explains depth and max_properties, which are the main customization knobs. The missing 'target' parameter is a notable omission, but the tool is otherwise well-covered for its 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?

The schema has 0% description coverage, so the description must compensate. It explains depth and max_properties well and mentions operation_id, method, and path as identification mechanisms. However, the 'target' parameter is completely absent from the description, leaving its meaning unclear. This gap prevents a higher score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Show the full signature of one API operation before calling it.' It identifies the specific resource (one API operation) and the verb 'Show', distinguishing it from siblings like vcf_call (which actually invokes) and vcf_search_api (which finds operations).

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?

Explicit guidance is provided: 'Always do this before a POST/PATCH/PUT' and 'Identify the operation either by operation_id (from vcf_search_api) or by method plus path.' This tells the agent exactly when to use this tool and how to specify the operation, while implying it is a pre-call step.

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 two important behaviors: unreachable appliances are reported inline instead of failing the whole snapshot, and per_section_limit controls summarization. It also reveals that targets defaults to 'all with a recipe.' These details materially affect how the agent interprets the result, exceeding what annotations alone 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 description is front-loaded with a punchy summary, followed by a clarifying sentence on scope, a behavioral note, and a short Args list. Every sentence adds value—none are tautological or redundant. It is compact while still covering purpose, behavior, and parameters.

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

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

Given the tool's broad scope (inventory across multiple VCF components) and lack of an output schema, the description adequately explains what is returned (domains, clusters, hosts, gateways, alerts), how sections work, and how failures are handled. It is complete enough for an agent to decide when to use it and what to expect.

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 has no descriptions and 0% coverage, so the Args section carries the full burden. It explains 'targets' as a restriction to specific appliances with a default of all, and 'per_section_limit' as the item count before summarization. This gives clear, actionable meaning beyond the bare schema types and defaults.

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 'Snapshot the estate: domains, clusters, hosts, gateways, alerts,' providing a specific verb and resource. It further clarifies the cross-system scope ('across SDDC Manager, vCenter, NSX and Operations') and positions it as a one-call overview tool, clearly distinguishing it from sibling tools like vcf_targets or vcf_search_api.

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 'One call that answers "what have I got?"' clearly establishes the intended use case for high-level estate snapshots. It also explains behavior on unreachable appliances, which sets expectations in failure scenarios. However, it does not explicitly name alternative tools or state when to avoid this tool, so it is a clear context without explicit exclusions.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: results are ranked and include method, full path, summary, and operationId. It also explains the include_deprecated behavior, providing useful details beyond 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: a brief statement of purpose and scale, followed by practical usage guidance, then a clear list of argument descriptions. Every sentence adds value, and the examples ('commission hosts', 'rotate passwords') make the tool's intent immediately understandable without unnecessary verbosity.

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 explains what results contain (method, path, summary, operationId) and how they are ordered (ranked). It covers all parameters, provides context for the deprecated filter, and gives performance expectations (~7,700 operations). The description is complete for this search 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 description coverage is 0%, so the description carries the full burden for parameter semantics. It explicitly describes all five parameters: query, target (with appliance list), method (HTTP verbs), limit (default 25), and include_deprecated (VCF 9.1 deprecation). This fully compensates for the missing 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 clearly states the tool's function: 'Find VCF API operations by intent, across ~7,700 indexed operations.' It uses a specific verb (find) and resource (VCF API operations), and distinguishes itself from siblings like vcf_describe_api and vcf_call by focusing on search/discovery rather than describing or executing specific operations.

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 usage context: 'Search the way you would describe the task... rather than guessing a path.' It advises on using the target parameter when the appliance is known. However, it does not explicitly mention when not to use this tool or name alternative tools for related tasks, stopping short of a full when/when-not specification.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds value by disclosing the return content (name, product, address, auth scheme, operation count, reachability) and emphasizing the importance of the target name. It does not contradict 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 concise and well-structured: a one-sentence purpose statement, a short 'Start here' directive, a list of return fields, and a note about the target name's role in other tools. Every sentence earns its place, and the key information 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 simple listing tool, the description covers the main purpose, the content of the output, and how to use the results with sibling tools. The one gap is the lack of explanation for the check_reachability parameter, but the overall guidance is sufficient for an agent to invoke 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?

The schema has one parameter, check_reachability, with no description in the schema (0% coverage). The tool description does not mention this parameter at all, so it fails to compensate for the missing schema documentation. The parameter name alone is insufficient to explain its effect, especially since the description mentions reachability only in the return list, not tying it back to the 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 clearly states the tool's function: 'List every VCF appliance this server can talk to.' It uses a specific verb (list), a specific resource (VCF appliance), and immediately distinguishes this tool as the entry point by saying 'Start here' and noting that the target name is expected by other 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 provides explicit guidance on when to use this tool: 'Start here.' It also explains that the returned target name is what every other tool expects, which tells the agent to use this tool first to get identifiers for subsequent operations. This is strong contextual guidance, even without naming alternatives explicitly.

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 key behaviors beyond the annotations: it reports status, failure subtask and reason, and explains the polling behavior controlled by wait_seconds. No contradictions with the readOnlyHint/idempotentHint 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 concise, front-loaded with the core purpose, and well-structured with a short intro, context, and Args list. Every sentence contributes value 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?

The description provides sufficient context for a straightforward polling tool, including when to use it and what to expect on failure. It lacks explicit return format details (no output schema) and omits poll_interval, but overall covers the essential operational aspects.

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 description adds meaning for target (sddc or installer), task_id (returned by vcf_call), and wait_seconds (poll vs single check). However, it omits poll_interval entirely, leaving this parameter undocumented since schema coverage is 0%.

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 checks or waits on a long-running VCF task and reports status, including which subtask failed and why. It distinguishes itself from vcf_call by explaining that mutations return a task id, which this tool then monitors.

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: use this after a mutation returns a task id, and it can check once or poll until terminal. It does not explicitly name alternatives, but the context is sufficient and the default behavior (wait_seconds=0) is explained.

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 flag readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds substantial behavioral context: it does not execute, it polls to completion, it resolves the validation twin automatically, and it returns validated true/false plus each failed check. It also covers the edge case for non-conforming targets, which is not derivable from 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 detailed but every sentence earns its place. It front-loads the most critical fact ('WITHOUT executing it'), then explains the validation-twin pattern, the return format, the edge case, and finally parameter details in a structured list. It is neither bloated nor under-specified.

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 having no output schema, the description discloses the return shape (validated true/false plus failed checks) and clarifies the polling behavior. It covers the main usage flow, the automatic twin resolution, and the fallback for targets without /validations. For a tool of this complexity, the description is 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?

The input schema has zero description coverage for all four parameters, yet the description's Args section clearly explains each: target (appliance name, with guidance on which have the richest surface), path (the actual operation or its /validations path), body (same JSON body as the real operation), and wait_seconds (poll duration). This fully compensates for the schema 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?

The description opens with a specific verb and resource: 'Test a spec against VCF's validation endpoint WITHOUT executing it.' This immediately distinguishes it from execution-oriented siblings like vcf_call. The explanation of validation twins further clarifies the purpose and the relationship to mutating endpoints.

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 frames usage as 'the safe way to iterate on a spec before committing it,' signaling when to use it instead of actual execution. It also describes behavior for targets lacking the standard convention (fallback to listing check-style operations), giving practical guidance. The mention that sddc and installer have the richest validation surface adds targeting advice.

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