VIL ZERO

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description does add content-level value by enumerating what is returned (interfaces, intents, commerce rules, protocol), which annotations cannot express, but it says nothing about size, variability, or whether the payload must be acted on before other calls.

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; the returned resources are listed immediately. It is terse to the point of terseness — 'preferred protocol' and 'commerce rules' are handed over without unpacking — but no sentence 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?

With no output schema and no parameters, the description is the only source of return-shape information, and enumerating the four payload categories is genuinely useful. However, for a discovery/handshake tool whose whole purpose is telling the agent what comes next, it omits sequencing and payload structure, leaving a meaningful gap.

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?

Zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies since the schema is trivial and fully consistent with the no-argument 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?

Specific verb (Return) plus a concrete list of resources returned: machine interfaces, supported intents, commerce rules, and preferred protocol. An agent can infer this is a discovery/bootstrap endpoint, though the 'handshake' framing and 'VIL ZERO' jargon are never explained, so it's clear-but-not-perfectly-differentiated from siblings like find_capability or list_capabilities.

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 when-to-use guidance at all. It doesn't say this is typically the first call, nor how it relates to find_capability/list_capabilities/system_status. The agent must guess whether to call it before or instead of 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 declare readOnlyHint=true and openWorldHint=true, so the safety and external-world profile is covered. The description adds 'live', which signals real-time data freshness, but says nothing about how ranking is computed, result ordering, or any rate/call constraints implied by openWorldHint.

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 or repetition, which is appropriately sized for the message. Its brevity is efficient, though it is close to under-specification rather than true economy.

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 two-parameter tool with no output schema and no parameter documentation, the description leaves key gaps: what a 'capability' is, what the ranking returns (scores? ordered list?), and what 'limit' controls. The agent has annotations for safety but not enough to invoke the tool confidently.

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% and neither of the two parameters is explained anywhere. The description's phrase 'against a machine requirement' loosely gestures at the 'query' parameter but gives no format, syntax, or examples, and it never mentions 'limit' or its 1-20 bound.

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 ('Rank') and resource ('live VIL ZERO capabilities') plus the target of the ranking ('a machine requirement'), which is enough for an agent to know this is a scored search rather than a plain listing. It implicitly contrasts with list_capabilities (rank vs. enumerate) but never names or explicitly differentiates from that 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?

No when-to-use guidance is given: nothing says when to pick this over list_capabilities or submit_need, and there are no prerequisites, exclusions, or fallback conditions. The agent must infer the use case entirely from the verb 'Rank'.

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 openWorldHint=true, so the safety profile is covered. The description adds that the set is dynamically 'currently available', but says nothing about result volume, pagination, or freshness/caching, which matter for a live catalog read.

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, which is appropriately sized for a no-argument listing tool. The payoff is reduced by opaque domain jargon ('VIL ZERO') that costs the reader comprehension without adding 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 and no parameters, the description carries the burden of explaining what a returned capability looks like and whether results are paged or filtered. It does not, so an agent cannot anticipate the response shape from the definition alone.

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 and schema coverage is 100%, so there are no parameter semantics to clarify. Baseline 4 applies; there is nothing the description could add here.

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?

Uses a specific verb ('List') plus a scoped resource ('VIL ZERO machine-created micro-services currently available to agents'), so an agent knows it enumerates a live catalog. It does not explicitly contrast with the sibling find_capability, which also targets capabilities, leaving the list-vs-search distinction to inference.

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 stated when-to-use, when-not-to-use, or alternative ('use find_capability when you already know the capability name'). The word 'currently' hints at a discovery use case but gives no explicit routing guidance against the eight 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds only 'current state', which restates the read semantics and says nothing about auth requirements, rate limits, or error behavior for an unknown orderId. With annotations carrying the load, this adds essentially no 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?

One short sentence with zero filler, and the key resource qualifier ('VIL ZERO PayPal order') is front-loaded. Nothing is padded or redundant.

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 should indicate what 'state' is returned (status values, amount, payer info) and what happens on an invalid orderId. It omits both, leaving the agent unable to interpret the response or handle failures.

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% for the single required orderId parameter, so the description must compensate and does not — it gives no format, source, or example for the PayPal order identifier. An agent cannot tell from either field whether orderId is the PayPal order ID or an internal reference.

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 (retrieve) and resource (the current state of a VIL ZERO PayPal order), so an agent can tell it is a read of order state rather than a capability or payment action. It does not explicitly contrast itself with siblings like report_payment or quote_purchase, but the named resource is specific enough to be recognizable.

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 when-to-use guidance is given: nothing says when an agent should call this versus quote_purchase/report_payment, nor what preconditions exist (e.g. an order must already exist). The agent must infer all usage context from the tool 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?

Annotations declare destructiveHint=false and openWorldHint=true, covering the safety profile, and the description usefully adds that the result carries manual PayPal payment instructions. However, it does not disclose that this creates persistent server-side state requiring a valid businessId, nor any auth or idempotency behavior beyond what the write-oriented annotations imply.

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 short sentence with the action front-loaded and no padding. It is terse rather than verbose; the only cost is that its brevity reflects under-specification rather than efficient information density.

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 mutation tool with no output schema and 0% parameter documentation, the description should carry the full explanatory load, yet it omits parameter meaning, prerequisite state, and the shape of the returned payment instructions. What exists is a fragment of the picture.

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% and the description says nothing about either parameter. An agent cannot learn from this text what businessId identifies, whether it must be pre-existing, or what requestedCalls counts or its valid range, so the description fails to compensate for the empty 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 names a verb and a resource ('Create a machine order'), but the resource conflicts with the tool name and title ('quote'/'purchase quote'), leaving the agent unsure whether a quote or an order is produced. It does not distinguish itself from siblings such as order_status or report_payment, which sit adjacent in the purchase flow.

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

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

There is no statement of when to call this versus siblings like order_status or report_payment, and no prerequisites (e.g. needing a businessId that already exists). The phrase 'manual PayPal payment instructions' hints at a checkout context but the description never tells the agent where this fits in the flow.

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 this is a write (readOnlyHint=false), non-destructive, and open-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing that the reported status stays unverified because PayPal is not connected, which is a key side-effect caveat an agent would not otherwise 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?

Two short, front-loaded sentences with no filler. The action comes first and the important caveat second.

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 and no annotation detail on the return, but the description helpfully explains the unverified status outcome. It still leaves gaps around what orderId identifies and what (if anything) is recorded or returned.

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 carry the load, but it only obliquely references 'transaction reference' and never mentions the required orderId parameter or any format expectations (e.g., that the reference must be at least 2 characters).

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 ('Report a PayPal transaction reference'), making the action clear. However, it does not differentiate itself from related siblings like order_status or quote_purchase, so an agent must infer the boundary.

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 no explicit when-to-use or when-not-to-use guidance and names no alternatives. The reader can only infer that this tool is for attaching a PayPal reference to an order, without knowing how it relates to order_status.

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 openWorldHint=true, so the safety profile is covered. The description adds 'current' (freshness framing) and 'public' (visibility scope), which is modest added value; it says nothing about refresh cadence, rate limits, or what an autonomous Scout run actually yields.

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 first and no filler. It is efficient, though the compounded noun list is slightly dense rather than maximally sharp.

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 load of explaining what comes back, and it only names three categories without describing shape or content. For a snapshot tool whose return is the whole point, this is adequate but thin.

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 there is no per-parameter semantics to document; the baseline for a parameterless tool applies. The description correctly implies the snapshot is unfiltered, which is consistent with an empty 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 ('Return') and names the resources: 'public demand signals, clusters, and autonomous Scout runs.' This is more than a restatement of the name/title, though 'Scout runs' is jargon and no sibling (e.g. find_capability, list_capabilities) is contrasted to aid selection.

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 when-to-use context, prerequisites, or alternative routing is given. With siblings like find_capability, list_capabilities, and system_status available, an agent gets no signal about when a snapshot is preferable to those.

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 openWorldHint=true, so this being a write-style request is covered. The description adds real context the annotations lack: automatic matching against existing capabilities and possible escalation to Factory on repeated demand. It still omits what actually happens on submission and how the numeric parameters shape the request.

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, front-loaded with the action and followed by the relevant matching/escalation behavior. Every clause 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 mutating, open-world tool with no output schema and 0% parameter documentation, the description should explain the meaning and effect of maxPrice and deadlineSeconds and what a submission does or returns. As written, an agent cannot confidently supply the two optional numeric arguments.

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% and the description explains none of the three parameters. maxPrice (a maximum of 1000) and deadlineSeconds (max 900) are opaque to an agent with no explanation of whether these are a bounty price, a timeout, or something else.

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: 'Submit a missing capability,' which is clearly distinct from find_capability and list_capabilities among siblings. However, it never names those siblings, so the agent must infer the boundary between searching and submitting.

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?

'Existing capabilities are matched first' implies you should check for an existing capability before submitting, but it stops short of naming find_capability or stating when not to submit. Usage is strongly implied rather than explicit.

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 openWorldHint=true, so the safety profile is covered. The description adds the payload shape (health, commerce mode, capability count), which is useful given there is no output schema, but it says nothing about freshness, rate limits, or auth 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?

A single front-loaded sentence with no wasted words; every listed item is a distinct returned datum.

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 zero-parameter diagnostic tool with no output schema, the description enumerates the main return categories and is largely sufficient. It stops short of full completeness by omitting any note on call context or the shape of nested 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 tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to clarify or compensate for.

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 ('Return') and enumerates the resources surfaced: machine interfaces, Scout health, commerce mode, and sellable-capability count. This lets an agent distinguish it from status-adjacent siblings like scout_snapshot and list_capabilities, though it doesn't explicitly name those alternatives.

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 siblings such as scout_snapshot (health) or list_capabilities (capability counts), nor any prerequisites or trigger conditions. The agent must infer the use case from the field list alone.

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