PacketFabric

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

Annotations declare readOnlyHint=true, but the description says writes can create/modify/delete and may create billable services when PF_ALLOW_WRITES=true. That directly contradicts the read-only annotation.

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 tight sentences front-load the core dispatcher purpose and the write-safety rule. No filler; the approval instruction is essential.

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?

Has an output schema, high schema coverage, and covers the crucial write-gating/confirm behavior. Still, as a generic open-world API caller it could say more about auth/error behavior, but the key invocation guidance is present.

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

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

Schema coverage is 100%, and every parameter has a schema description, so the baseline is 3. The description adds confirm workflow and operation_id sourcing but little parameter-level meaning beyond the schema.

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

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

States a specific verb and resource: call any PacketFabric API endpoint using operation_id. It points to pf_search_endpoints as the source of operation_id, but does not explicitly contrast with pf_describe_endpoint or other siblings.

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

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

Explains read vs write behavior and the required preview/approval flow before confirm=true. It gives clear conditions but no explicit when-not or alternative-tool routing beyond sourcing operation_id from pf_search_endpoints.

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 a little context by naming the three things it surfaces, but discloses nothing further about behavioral traits. With annotations carrying the load, a 3 is appropriate.

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 waste. The capability statement is front-loaded ahead of the workflow instruction, making the important information land first.

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 the description need not explain return values, and it correctly focuses on purpose and workflow. The only gap is that operation_id's origin is never addressed, which slightly limits standalone completeness.

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 there is one required parameter (operation_id) whose meaning and provenance are never explained in either the schema or the description. A discovery tool depends on the agent knowing where operation_id comes from (e.g. pf_search_endpoints), and the description does not say so.

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: it returns parameters, request-body schema, and response shape for a single endpoint. This clearly distinguishes it from pf_call_endpoint (which executes) and pf_search_endpoints (which locates), so an agent can tell them apart without opening a 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 an explicit routing rule: 'Call this before pf_call_endpoint for anything you haven't used yet.' The condition (unknown endpoint) and the alternative (pf_call_endpoint) are both named, leaving nothing to inference.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the categories of location data available, but it does not disclose pagination behavior, rate limits, or other operational details beyond the output schema.

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

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

The description is a single front-loaded sentence with no wasted words. It is concise, though it provides little structure for an 11-parameter search 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?

The output schema and annotations reduce the description's burden, but for an 11-parameter location search, the lack of filter guidance and usage context leaves meaningful gaps. It is minimally adequate for an agent that already understands the PacketFabric location model.

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 11 parameters and only 55% schema description coverage, several filters such as nat_capable, ipsec_capable, near_cloud_router, city, and state are not explained in the description. The description mentions broad data categories but does not map them to parameter semantics or add meaning beyond the schema.

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

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

The description gives a specific verb and resource: 'Find PacketFabric locations / POPs.' It also lists the kinds of location data involved, but it does not explicitly distinguish this tool from any 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?

There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The purpose implies a location search, but usage must be inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds that the call doubles as a credential/connectivity smoke test and lists the identity fields returned. It does not describe error behavior when credentials are invalid, which would complete the picture.

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 with zero filler; the resource and its payload come first and the recommended usage follows. 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?

With no parameters, read-only annotations, and an output schema covering return values, the description needs only to say what is fetched and why it matters, which it does. Nothing required to invoke the tool correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly signals the no-argument nature by framing it as a simple identity fetch.

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 (get the current PacketFabric customer account) and enumerates the returned fields (name, account number, UUID, type). No sibling tool in the list retrieves account-level identity, so an agent can distinguish it immediately.

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?

"Good first call to confirm credentials work" gives a clear usage context and a recommended ordering relative to other calls. It stops short of naming when not to use it or pointing to an alternative, so it is not a full 5.

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 only the temporal scope (current and upcoming) and says nothing about auth requirements, rate limits, or result freshness, which is a modest addition for a read-only 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?

A single front-loaded sentence that states the resource, temporal scope, and optional filter with zero filler. 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?

With an output schema covering return values and annotations covering the read-only/open-world nature, the description is nearly sufficient for a simple read tool. It could note pagination or result limits given the max_items parameter, but the core 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?

Schema coverage is 100%, so all three parameters (pop, market, max_items) are already documented with examples and constraints in the schema. The description mentions POP/market filtering but adds no syntax or semantics beyond what the schema provides, making the baseline 3 correct.

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 specific resource (maintenance windows) and scopes it (current and upcoming), with an optional filter dimension (POP or market). It is clear what the tool returns, though it omits an explicit verb and does not need sibling differentiation since no other sibling covers maintenance.

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

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

The phrase 'optionally for a POP or market' implies how to narrow results, giving some usage signal. However, there is no explicit when-to-use guidance, no prerequisites, and no exclusions or alternatives to consider.

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 only the identifier format example and nothing about depth of detail or any rate/auth considerations, so it adds modest value over the annotations.

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

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

A single front-loaded sentence that states action, resource, scope, and identifier format with zero filler.

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

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

For a single-resource getter with an output schema present, the description need not explain return values. It gives the verb, resource, and lookup key, which is enough to invoke correctly; only the usage routing against siblings is 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?

Schema description coverage is 0% with one parameter, so the description carries the burden. It does add the example format "PF-AP-LAX1-1234", which conveys the expected identifier shape, but gives no other semantics such as validation rules or case sensitivity.

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 ("Get full details for one port") and specifies the lookup key (circuit id). The "one port" scoping implicitly distinguishes it from sibling pf_list_ports, though no sibling is named 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?

The phrase "by circuit id" clarifies the required lookup method, giving implied usage. However, it offers no when-to-use context or explicit routing against alternatives like pf_list_ports or pf_find_locations.

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, and the description's 'no order is created' largely restates the read-only hint. It adds pricing semantics (MRC/NRC) but says nothing about rate limits, pagination behavior for the 5000-item cap, or what an empty pricing result means — modest added value against a low annotation-driven bar.

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, purpose front-loaded, zero filler. The glossary sentence is compact and directly resolves an unreadable enum token.

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 values need not be explained, and the description covers purpose, read-only status, and pricing terms. The main residual gap is routing guidance against the many sibling pf_list_* and pf_find_locations tools, which the description never addresses.

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 78%, just under the high-coverage baseline, and most parameters carry their own descriptions. The description still adds genuine value by glossing an otherwise opaque enum value ('vcbwc = backbone virtual circuit bandwidth'), which the schema's 17-value product_type enum does not explain anywhere.

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 ('look up list pricing (MRC/NRC) for a PacketFabric product between locations') with clear scope, and the MRC/NRC framing distinguishes it from sibling list_* tools that enumerate resources rather than price them. An agent can tell this is a pricing-estimate tool, not a provisioning tool, 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?

'Read-only, no order is created' implies the intended use case (previewing cost before ordering), which is useful implied guidance. However, no sibling tool is named as an alternative and there is no explicit when-to-use/when-not-to-use statement, so 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond the name: no mention of data freshness, rate limits, pagination, or what happens when the VC is not on the port. With annotations carrying the main burden, this leaves the description thin.

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 that front-loads the resource and its scope; nothing is wasted. It is arguably terse to the point of under-specification, but there is no filler.

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

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

An output schema exists, so return values need not be explained, and the schema documents most parameters. However, for a 6-parameter tool there is no guidance on defaults (e.g., '24 hours ago', 'now') or on choosing this tool over sibling port tools, leaving a real 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?

Schema description coverage is 67%, with since, interval, vc_circuit_id and port_circuit_id documented inline. The description restates the port-vs-VC distinction that the schema already explains and adds nothing about type or until. Baseline 3 is appropriate when the schema does most of the work.

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 specific verb+resource: a traffic rate time series for a port, with an optional VC scope. It is clearly distinct from siblings like pf_get_port or pf_list_ports, though it does not name those siblings explicitly to sharpen the distinction.

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 use this tool versus alternatives (pf_get_port, pf_list_ports), nor any prerequisites or exclusions. The parenthetical about VC scope is the only usage hint, and it is applied implicitly rather than as 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 openWorldHint=true, so the safety profile is covered. The description adds that results include read/write operation counts, but since an output schema exists that content is largely already documented, so the marginal behavioral disclosure is modest.

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, with the resource and its payload front-loaded and the usage pointer second. Every sentence earns its place.

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

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

For a zero-parameter discovery tool with an output schema and read-only annotations, the description supplies everything needed: what it lists, what the listing contains, and where it fits in the workflow.

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, which is the baseline-4 case. There is nothing for the description to clarify beyond confirming the call is argument-free.

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 (areas/tags of the PacketFabric API) plus the payload the caller gets (read/write operation counts). It also distinguishes itself from the search-style sibling by naming pf_search_endpoints as the follow-up step.

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

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

"Use this to orient yourself before pf_search_endpoints" gives clear workflow context and an explicit alternative to reach for next. It stops short of stating when NOT to use it (e.g., if you already know the area), so it is not fully exhaustive.

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 resource scope and the hosted/dedicated distinction, but says nothing about pagination, filtering behavior, or ordering that the schema doesn't already 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 tight sentence that front-loads the verb+resource and defers the qualifier. 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?

An output schema exists, so return values need no explanation, and annotations cover safety. However, for a list tool with a search parameter and a result cap, the description does not address filtering, pagination, or how this differs from pf_list_cloud_router_connections.

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%: 'fields' and 'max_items' are documented in the schema, while 'q' is undocumented and 'kind' is carried by its enum. The description restates the hosted/dedicated values in prose, adding mild value but nothing about what 'q' searches, so baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('Layer-2 cloud connections'), plus the domain scope (AWS, Azure, Google, Oracle, IBM) and the two variants (hosted/dedicated). It is clear on its own, but does not explicitly differentiate itself from the close sibling pf_list_cloud_router_connections, so it stops short of a 5.

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

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

There is no when-to-use guidance, no exclusions, and no named alternative despite a very similar sibling (pf_list_cloud_router_connections). The agent must infer context purely from the tool 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and openness are covered. The description adds only that the listing spans five clouds and connection facets; it says nothing about pagination, truncation at max_items, or ordering that would go beyond the structured fields.

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 sentence, front-loaded with the verb and resource, with the scoping detail in a single parenthetical. No filler and nothing to remove.

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 structure need not be explained, and annotations cover the safety profile. For a three-parameter read-only list tool this is essentially sufficient; only an explicit disambiguation from sibling list tools is missing.

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

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

Schema description coverage is 100%, so each parameter (fields, max_items, cloud_router_circuit_id) is already documented in the schema; baseline 3 applies. The description's "for one router" loosely maps to cloud_router_circuit_id and "ports, IPsec" loosely maps to fields, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (List) and resource (Cloud Router connections), plus what a connection spans (AWS/Azure/GCP/Oracle/IBM, ports, IPsec) and the scope (account-wide or one router). It does not address the nearby sibling pf_list_cloud_connections, which is the main lexical ambiguity an agent would face, so it stops short of a 5.

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

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

"across the account or for one router" implies the two usage modes and signals that filtering is optional, but there is no explicit when-to-use, when-not-to-use, or named alternative to pf_list_cloud_routers / pf_list_cloud_connections. Usage is inferable but not 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that each router carries ASN, capacity and region data, but says nothing about pagination despite max_items existing, nor about ordering or volume limits.

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 zero filler or restatement of the tool name. Every clause (resource, scope, returned attributes) 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?

An output schema exists, so return values need not be spelled out, and with two optional, fully documented parameters the definition is nearly sufficient. Only the omission of any usage routing against the four sibling 'list' tools keeps it short of 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 100%, so both optional parameters (fields, max_items) are already fully documented in the schema. The description adds no syntax or usage detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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 Cloud Routers') and adds scope ('on the account') plus the returned attributes (ASN, capacity, regions). It is distinguishable from siblings like pf_list_cloud_connections or pf_list_cloud_router_connections by resource name, though it never names an alternative 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?

No guidance on when to choose this over pf_list_cloud_connections or pf_list_cloud_router_connections, and no prerequisites mentioned. The only implied context is the account-level scope.

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 nothing beyond that: no pagination behavior, no note that results are capped by default at 100 items, no indication of what a 'point-to-point service' contains. It essentially restates the tool name.

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 resource and qualifier front-loaded and no filler. It is well-sized, though the terseness tips into under-specification rather than optimal 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?

An output schema exists, so return values need not be described, and max_items/fields are covered by the schema. However, for a list tool the unexplained 'q' filter and the absence of any scoping or filtering guidance leave the definition only minimally complete.

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

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

Schema coverage is 67%: 'fields' and 'max_items' are documented, but 'q' appears only as a bare title with a null default and no description anywhere. The description does not explain what 'q' searches, so the one opaque parameter is left entirely unexplained.

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 a specific resource ('point-to-point (wavelength-style) services'), with the parenthetical disambiguating the domain jargon. It does not, however, distinguish itself from the nearby pf_list_services or pf_list_ports siblings, leaving the agent to infer which list applies.

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 guidance, no conditions or prerequisites, and no mention of alternatives such as pf_list_services. The agent must guess whether this is the right listing tool for a given intent.

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 results include speed, status and POP, but says nothing about pagination, the interaction of max_items with truncation, or result volume — context an agent listing up to 5000 items would want.

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 scope front-loaded and no filler. 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?

An output schema exists, so return-value detail is unnecessary, and the readOnlyHint covers safety. The remaining gap is the absence of filtering guidance for the eight optional parameters, which the 63% schema coverage only partially fills.

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 63%, and the description names no parameters at all; the three undocumented booleans (is_lag, is_ptp, is_cloud) get no explanation anywhere. Worse, 'POP' is presented as a returned attribute rather than also being a filter parameter, which can mislead an agent about how to filter.

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 ('List') and resource ('the account's ports') and enumerates the port subtypes (physical access, LAGs, cloud ports) plus returned attributes (speed, status, POP). It does not explicitly contrast with overlapping siblings like pf_get_port or pf_list_point_to_point, so it falls short of a 5.

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

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

Listing is implied as the operation, but the description never states when to use this versus pf_get_port (singular) or the point-to-point/cloud-router listers. There are no exclusions or prerequisites, leaving routing to the agent's 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the account-level scope but says nothing about pagination behavior, the default 100-item cap, or how filters combine — all knowable only from the schema, not the prose.

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 that names the verb, the resource, and the covered categories with zero filler. 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?

An output schema exists, so return values need no explanation, and the schema fully documents all five optional parameters. The remaining gap is routing context — when to prefer this broad lister over the narrower sibling listers — which leaves the definition slightly under-complete for an agent choosing between near-duplicate 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 description coverage is 100%, so every parameter (q, fields, max_items, service_type, port_circuit_id) is already documented in the schema. The description's type enumeration loosely maps to the service_type enum values, adding marginal reinforcement but no new syntax or format detail. 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?

Specific verb (List) plus resource (the account's virtual circuits / services) with a parenthetical enumerating the covered types (backbone VCs, cloud connections, IX, marketplace). It is clearly broader than sibling listers such as pf_list_cloud_connections or pf_list_point_to_point, but the description never states that relationship, so the distinction is inferable rather than explicit.

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, no prerequisites, and no mention of the narrower siblings (pf_list_cloud_connections, pf_list_cloud_router_connections, pf_list_point_to_point) that return subsets of the same data. The agent must guess whether to call this broad lister or a type-specific one.

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, covering the safety profile. The description adds useful workflow context that results are operation_ids for describe/call, but it does not discuss pagination, limits, auth, or result behavior; with annotations carrying safety, this is adequate but not rich.

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 purpose and followed by the return/handoff workflow. No wasted text.

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 annotations, 75% parameter coverage, and an output schema, the description provides enough to understand the tool's role in endpoint discovery. It omits pagination/limit details, but those are either covered elsewhere or less critical.

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 75% and already describes tag, query, and read_only; the description only restates keyword search. It adds no filter semantics beyond the schema, and limit remains undocumented.

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: search all PacketFabric API endpoints by keyword. It also names the return artifact (operation_ids) and downstream tools, clearly distinguishing it from pf_call_endpoint and pf_describe_endpoint.

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?

Explains the discovery workflow: search by keyword, then pass returned operation_ids to pf_describe_endpoint or pf_call_endpoint. It does not explicitly say when to prefer pf_list_api_areas or when not to search, so it falls short of a full 5.

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