pbs_namespaces_list

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

The description explicitly labels the operation as 'read-only', which is critical for behavioral transparency. It also describes the return value: each namespace's hierarchical path (the ns field). However, it does not disclose potential errors, rate limits, or authentication requirements, but given no annotations, it sufficiently conveys the safe, read-only behavior.

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

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

The description is extremely concise, consisting of two sentences. The first sentence states the core purpose and read-only nature, and the second sentence details output and provides an alternative. Every word serves a purpose; no fluff or repetition.

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 that an output schema exists, the description does not need to detail every return field, but it mentions the key 'ns' field. The description covers the primary use case and filtering options. It could explicitly mention that the 'store' parameter is required, but that is clear from the schema. Overall, it provides sufficient context for an agent to use 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?

With 100% schema coverage, the baseline is 3. The description adds meaning beyond the schema by mentioning the output field 'ns' (hierarchical path) and explaining that filtering is hierarchical (parent namespace and recursion depth). This enriches the understanding of how parameters affect results.

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 verb 'List' and the resource 'namespaces within a PBS datastore', and explicitly mentions the optional hierarchical filtering and read-only nature. It also distinguishes from the sibling tool pbs_namespace_create by directing users to that tool for adding namespaces.

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 explains the optional parameters for filtering by parent namespace and recursion depth, giving context on when to use the tool. It provides an alternative for adding namespaces (pbs_namespace_create), though it does not explicitly state when not to use the tool or other alternatives for listing.

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