List available scenarios

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantive behavioral disclosures: 'returns no customer data', 'Read-only, offline, deterministic', and 'Filtering by an area with no entries returns an empty list rather than an error.' These provide context that annotations alone do not convey, such as offline operation and the error-handling policy.

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 three sentences, each serving a distinct purpose: what the tool returns, how to use it in the workflow, and clarifying its non-live nature and edge-case behavior. It is front-loaded with the core listing purpose and immediately actionable next-step guidance.

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

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

Given the tool's simplicity (one optional parameter, output schema present), the description fully covers purpose, usage, behavioral traits, and edge cases. No further elaboration is needed; the output schema handles return-value details.

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

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

The schema already provides 100% coverage of the sole parameter 'area' with a detailed description and enum values. The tool description adds little beyond the schema, except the empty-list behavior context, which is more a behavioral trait than parameter semantics. Baseline 3 is appropriate as schema carries the descriptive burden.

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 uses a specific verb ('List') and clearly defines the resource: 'every Partner Center REST operation this server knows about, as a compact index of id, title, area, method, resolved url, and auth type.' It explicitly distinguishes itself from siblings like pc_get_scenario (full record) and pc_generate_call (code), making the purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Start here to discover what is available and to find the scenario id that the other tools take; then call pc_get_scenario for the full record or pc_generate_call for code.' It also clarifies that it is not a live query (returns no customer data) and describes the empty-list behavior for filtering, covering both when-to-use and behavioral expectations.

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