Answer a question about how Partner Center behaves

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'Read-only, offline, deterministic' and 'Every entry carries the Microsoft Learn page it was read from and the date it was checked,' offering provenance and determinism not present in annotations. It does not discuss pagination or error behavior, but with annotations covering safety, the added context is meaningful.

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 multi-sentence but every sentence serves a purpose: examples of rule types, usage guidance, sibling differentiation, behavioral disclosure, and language warning. It is front-loaded with the core purpose. Slightly long but every clause earns its place, so no waste.

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 3 optional params, a thorough schema, annotations, and an output schema, the description fully covers the tool's role. It includes example use cases, explicit sibling exclusions, behavioral traits, data provenance, and language constraints. No major gaps remain for an agent to select and invoke it 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?

Schema coverage is 100%, but the description adds valuable guidance beyond the schema: 'Omit to search them all' for area, 'raise it when exploring an area rather than asking one question' for limit, and a critical warning to pass questions in English because 'the rules are written in the words Microsoft's documentation uses.' This significantly enriches parameter understanding.

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 'Answer questions about Partner Center's RULES rather than its endpoints' with concrete examples (cancellation windows, non-payment, promotion limits, GDAP expiry). It clearly distinguishes from sibling tools by naming pc_get_scenario, pc_explain_lifecycle, and pc_lookup_error for different use cases.

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 explicitly says 'This is the tool for' and provides example question types. It gives direct alternatives: 'For the endpoint that performs an operation use pc_get_scenario; for whether an operation is legal right now use pc_explain_lifecycle; for a specific error code use pc_lookup_error.' This is unambiguous when-to-use vs. when-not-to-use guidance.

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