ML-NTWX Agent Intelligence Layer

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond restating that this is a read operation, such as error behavior for unknown IDs or whether the result is cached.

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 a single well-formed sentence with no wasted words and the lookup key is front-loaded. It is appropriately sized, though its brevity leaves usage and parameter context underdeveloped.

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-by-ID tool with an output schema and rich annotations, this is minimally adequate. However, it omits when to choose it over sibling lookup tools and does not clarify the canonical ID source, which leaves a meaningful gap for an agent selecting among get_capability, list_capabilities, and match_capability_to_intent.

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 does add the phrase 'canonical capability ID,' but it does not explain where those canonical IDs come from or how they differ from other identifiers; the schema enum itself supplies the concrete allowed values.

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 ('Read a capability') and specifies the lookup key ('by canonical capability ID'). It is clear enough to distinguish from list_capabilities, but it does not explicitly differentiate itself from other single-resource getters like get_product or get_catalogue.

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 tool versus list_capabilities, match_capability_to_intent, or the other get_* tools. The retrieval-by-ID context is implied only by the phrase 'by canonical capability ID'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that the read is 'full' (complete catalogue), but says nothing about size, pagination, or cost of retrieving everything, which is the meaningful extra context for a full-dump 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 waste. The resource phrase is dense ('product, capability and indicative-offer catalogue') but still earns its place by describing the scope of the dump.

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

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

The tool is simple (no params), annotations are complete, and an output schema exists so return values need not be explained. The remaining gap is sibling routing against list_capabilities and get_capability, which the description only hints at via 'full'.

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 rule this scores 4. There are no parameter semantics to elaborate beyond what the empty schema already conveys.

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 (Read) and resource (the full registry product, capability and indicative-offer catalogue). The word 'full' implicitly distinguishes it from the single-item siblings get_product and get_capability, though it never names 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?

No explicit when-to-use or when-not guidance, and no alternatives are named. The 'full catalogue' framing implies use when you want everything rather than one capability (list_capabilities, get_capability), but that routing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds a useful domain constraint that live products yield no service-only path, but it does not clarify what happens when the filter matches a live product (empty result vs error) or how results are ordered.

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 operation and the optional filter. The second sentence is a useful caveat, though its phrasing ('Live products have no ... path') is slightly ambiguous about whether it describes a result condition or a validation rule.

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?

An output schema exists, so return-value structure need not be explained, and annotations cover safety. Still missing is a plain-language definition of 'engagement path' and clarification of the live-product edge case, which matter for correct invocation and interpretation.

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

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

Schema description coverage is 0%, but the schema's enum lists all six accepted product IDs, so the value space is visible. The description adds that the value is a 'canonical product ID', which is modest but useful semantic framing beyond the raw enum.

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: list engagement paths, scoped to 'service-only' products, with optional product filtering. It is distinct from siblings like get_product and list_capabilities. However, the core domain terms 'engagement path' and 'service-only' are undefined, so the agent knows the operation's shape but not fully what it retrieves.

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

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

The description says the filter is optional and notes that live products have no service-only path, but it gives no explicit guidance on when to call this versus get_product or list_capabilities. An agent has to infer usage from the noun phrase 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 already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the qualifier that IDs are 'canonical' (i.e., must come from the known set) but says nothing about not-found behavior or what a successful read returns, leaving little added 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 the verb and the key constraint up front. Nothing redundant or 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?

For a single-parameter lookup with an output schema and full annotations, the description is nearly sufficient. The only real gap is error/not-found behavior, which the caller may need to know.

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?

There is a single parameter whose schema uses an enum covering all valid values, so the schema itself effectively constrains input even at 0% description coverage. The word 'canonical' in the description adds the useful hint that the enum values are the only valid identifiers, but no format or sourcing detail is given.

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 ('Read a product') plus the lookup key ('by canonical product ID'), which is enough to distinguish it from siblings like get_capability and get_catalogue. It stops short of explicitly contrasting itself with those siblings, but the noun difference is clear.

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

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

No guidance on when to use this versus get_catalogue, get_capability, or list_capabilities. The only usage signal is the implied constraint that the ID must be canonical, which the caller must infer.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the optionality of filtering; it says nothing about ordering, pagination, or how the two filters combine.

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 front-loaded sentence with no filler. Every clause (what it lists, what can be filtered) 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?

The tool is simple and ships an output schema plus rich annotations, so most burden is off the description. Still missing is the semantics of combining the two optional filters and whether an unfiltered call returns everything, which matters because both filters are optional.

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%, but both parameters are closed enums whose accepted values are self-documenting in the schema. The description adds that filters are optional and that product takes a canonical product ID, but does not clarify AND/OR combination or default behavior when status is omitted.

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: 'List registry capabilities'. It contrasts implicitly with the singular sibling get_capability and the broader get_catalogue, so an agent can tell it returns a collection rather than one entry. No explicit sibling differentiation is made in text, keeping it at 4.

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?

'Optionally filtered by canonical product ID and status' implies when the filters apply and that both are optional, but there is no statement of when to prefer this over get_catalogue or match_capability_to_intent, nor any exclusion 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 cover safety traits: read-only, idempotent, non-destructive, and closed-world. The description adds meaningful behavior beyond annotations by specifying that routing is deterministic and that the tool does not perform product execution.

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 a single front-loaded sentence with no redundant text. Both clauses carry useful information: the default deterministic routing behavior and the no-execution constraint.

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 annotations and output schema mean the description need not explain return values or safety profile, and it adequately states the core routing behavior. Still, with a nested 'context' object and zero schema parameter descriptions, the description leaves input semantics underspecified.

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 does not explain the required 'intent' parameter or the optional nested 'context' parameter. It also does not clarify the meanings of 'preferred_product' or 'allow_service_engagement', so the description does not compensate for the absent schema documentation.

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 routing purpose: deterministically selecting navigation, engagement, or clarification. It also distinguishes this from execution-oriented tools by saying 'no product execution', though it does not explicitly say it matches capabilities by name.

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 implies this is the default routing tool and that it should not be used for product execution. However, it does not explicitly compare when to use this versus siblings such as get_capability or get_engagement_path.

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