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

The description goes beyond annotations by adding 'offline', 'deterministic', and 'issues no tokens, contacts no identity provider, avoids handling secrets', giving a precise safety profile. No contradictions with the readOnlyHint/idempotentHint/destructiveHint 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?

The description is three sentences, front-loading the core purpose, then usage guidance, then behavioral caveats. Every sentence contributes distinct value with no 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 to explain return values, and annotations cover safety. The description adds the missing pieces: when to use it, what it covers, and that it is offline and side-effect-free. It also provides clear alternatives, making it complete for agent decision-making.

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% with detailed enum descriptions for both cloud and authType. The description merely maps these to domain terms ('token flavour', 'national cloud'), adding no syntax beyond the schema, so the baseline score of 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?

The description opens with a specific verb ('Return') and clear resource (authentication guidance for Partner Center), scoped by token flavour and national cloud. It explicitly distinguishes itself from siblings by naming pc_check_auth and pc_decode_error.

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 explicitly states when to use the tool ('Use this when deciding or setting up how to get a token') and provides concrete alternatives for other scenarios ('To check whether existing code already uses a retired pattern, use pc_check_auth instead; to decode a 401/403 you already hit, use pc_decode_error').

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 description adds substantial behavioral context beyond the annotations: the request is never sent, the Authorization header is a placeholder, a fresh MS-RequestId is minted on each call for write operations (explaining the idempotentHint=false), unsupplied placeholders appear in missingParams instead of failing, and unknown IDs return ok:false with suggestions. This richly supplements the annotations without contradicting them.

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 structured paragraph with front-loaded purpose, followed by usage guidance, then important caveats. Every sentence earns its place, and despite being ~160 words, it packs detailed behavior without redundancy or fluff.

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 complexity (request assembly, auth headers, non-idempotency, error handling) and the existence of an output schema, the description covers all essential aspects: what gets returned (URL, headers, body skeleton), the non-sending nature, authentication behavior, retry guidance, and error behavior. It is complete enough for an agent to invoke correctly and interpret results.

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?

While the schema already describes both parameters at 100% coverage, the description adds meaningful semantics: values are URL-encoded automatically, key matching is loose ('customer-id', 'customerId', 'customerid' all work), and omitting params yields the URL with placeholders intact plus missingParams. This goes well beyond the schema, making it easy to use correctly.

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 opens with a precise verb and object: 'Assemble one Partner Center REST request as structured data,' and enumerates the output components. It clearly differentiates from siblings by naming pc_generate_call and pc_validate_request as alternatives, so an agent can easily distinguish this tool.

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?

Explicit 'Use this when' and alternatives are provided: 'For a language-specific code snippet use pc_generate_call instead, and to lint a request you already wrote use pc_validate_request.' It also suggests how to discover scenario IDs with pc_list_scenarios or pc_plan_* tools, giving clear contextual direction.

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?

Beyond annotations, the description discloses crucial behavioral traits: 'Read-only, offline, deterministic pattern matching: the snippet is not executed, nothing is sent anywhere, and no code is modified.' It also explains output behavior ('A clean snippet returns findings: [] with clean: true') and the limitation ('Detection is regex-based, so a clean result is not a guarantee of correctness').

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 well-structured and each sentence earns its place: purpose, usage, alternatives, safety guarantees, output format, and a caveat. It is front-loaded with the core action and tapers into additional context, with no wasted words.

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 linting tool with a detailed schema, clear annotations, and an output schema, the description is complete. It covers what, when, how, safety, output expectations, and limitations. Nothing essential 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 schema already covers 100% of parameter information with a rich description (any language, partial snippet fine, case-insensitive, secrets not transmitted). The tool description adds little beyond that, mentioning 'snippet' in context but not introducing new parameter semantics. Baseline 3 is appropriate because 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?

The description states a specific verb ('Scan') and resource ('Partner Center auth or client code snippet for retired and deprecated patterns'), listing exact patterns (graph.windows.net, ADAL, archived .NET SDK, AzureAD/MSOnline modules). It distinguishes itself from siblings by explicitly naming pc_auth_guidance and pc_migrate_from_sdk.

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 provides clear usage context: 'Use this to triage existing code before or after a 401.' It also names alternatives with specific guidance: 'For guidance on what to build instead, use pc_auth_guidance; to translate archived SDK calls into REST, use pc_migrate_from_sdk.'

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that the tool is offline and deterministic, never sends input anywhere, and never replays requests. It also explains the edge-case behavior of always returning ok:true with parsed fields and a note for unrecognized codes. This adds behavioral context well beyond what annotations provide.

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 dense but every sentence earns its place: purpose, usage trigger, alternatives, behavioral guarantees, and return behavior. It is front-loaded with the core purpose and uses concise language without 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?

Given the tool's complexity (handles raw, partial, or malformed input) and that an output schema exists, the description nevertheless covers input expectations, output guarantees (always ok:true), and follow-up guidance (note with next steps). It is fully self-contained for an agent to decide when and how to invoke it.

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 input schema has 100% coverage, with a detailed description of the 'error' parameter covering verbatim input, JSON or unstructured text, headers, and malformed input handling. The tool description itself does not add significant meaning about the parameter beyond what the schema already states, 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?

The description opens with a specific verb ('decode') and resource ('raw Partner Center error response'), and details exactly what is extracted (error code, HTTP status, MS-CorrelationId) and returned (causes, remediation, scenarios, support wording). It explicitly distinguishes from sibling tools like pc_lookup_error and pc_diagnose, making the tool's unique role 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?

It states the intended usage context: 'the right first tool when something failed and you have the response in hand.' It also provides clear exclusion criteria by naming alternatives (use pc_lookup_error when you have a clean code, pc_diagnose when you have only a prose description). This is textbook when-to-use 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that matching is heuristic, keyword-based, offline, deterministic, and that results can be empty or noisy. It also notes the always-ok:true return and fixed nextSteps checklist even on no match, providing rich behavioral 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?

The description is four sentences, each serving a distinct purpose: purpose, usage, alternative tools, and behavioral caveats. It is front-loaded with the core function and remains concise without 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?

Given the tool has a single parameter, an output schema, and rich annotations, the description covers all essential aspects: what it does, when to use it, how it behaves, and what it returns. There are no significant gaps.

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 input schema already provides 100% coverage of the single parameter 'symptom' with examples and keyword-matching details. The description adds usage context but no additional parameter syntax or format nuances beyond the schema, so the baseline of 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?

The description clearly states the tool matches a plain-language Partner Center problem against documented errors and returns candidates plus an ordered fix path. It explicitly contrasts with sibling tools pc_decode_error and pc_lookup_error, making its specific role unmistakable.

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 explicitly says to use this tool when there is no error body and no code, and directs users with raw responses or clean codes to more precise alternatives. This gives clear when-to-use and 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.

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral traits: 'Read-only, offline, deterministic.' It also explains what counts as a 'changed scenario' (route, auth, headers, request fields, response shape, constraints) and clarifies the tool's relationship to Microsoft Learn. No contradiction with 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?

The description is compact and front-loaded. The first sentence states the core function; the second explains use case; the third provides alternatives; final sentence gives safety traits. Every sentence serves a distinct purpose with 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?

Given the output schema exists, the description need not detail return format. It covers purpose, usage, alternatives, parameter interplay, and behavioral traits. For a moderate-complexity tool with good schema/annotations, this 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% for both parameters, so baseline is 3. The description adds value by suggesting a use case: 'Combine with `since` to ask whether one operation moved,' and discloses error behavior: 'A version with no recorded release comes back as ok:false listing the versions that do exist.' This goes 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 opens with a specific verb and resource: 'Return the scenarios added, changed, or removed across releases of this pack, newest first.' It clearly distinguishes this tool from siblings by naming alternatives (pc_whats_new, pc_get_scenario) and stating what this tool uniquely provides ('closest thing here to an API changelog').

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 explicitly states when to use: 'Use it to find out what moved since the version you last built against.' It gives clear exclusions and alternatives: 'For deprecations and enforcement deadlines use pc_whats_new instead; for one scenario's current detail use pc_get_scenario.' This is unambiguous 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, idempotentHint, and destructiveHint. The description adds 'Read-only, offline, deterministic,' which provides extra context beyond annotations (offline and deterministic are not captured by hints). It also describes the behavioral structure (failed preconditions return error codes). No contradictions.

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 well-structured: primary purpose first, then usage guidance, alternatives, and behavior notes. It is slightly verbose due to enumerating all nine operations, but every sentence contributes unique value. The layout is logical and front-loaded.

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 complex tool returning a state machine, the description covers what is returned, when to use it, alternatives, parameter behavior, and characteristics. The presence of an output schema means return values need not be detailed. Comprehensive for the task.

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% for the single `operation` parameter, and the schema description already states that omission returns every operation. The description repeats this guidance ('Omit `operation` for the whole machine') without adding new semantic information, so it stays at the baseline.

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 tool returns the subscription lifecycle state machine, enumerates the operations covered, and specifies the exact output components (legal states, fields to read, scenarios, error codes). It distinguishes itself from siblings like pc_get_scenario and pc_plan_subscription_change by positioning itself as the 'what can I do right now' reference.

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 explicitly states when to use this tool ('before reaching for an endpoint') and names specific alternatives with their use cases: 'For the endpoint itself use pc_get_scenario, for an ordered call sequence use pc_plan_subscription_change, and to decode a rejection use pc_lookup_error.' This is explicit when/when-not 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, 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.

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial context: 'Read-only, offline, deterministic,' 'the code is returned as text and is never executed,' placeholder credentials from environment variables, and the specific error behavior for unknown ids returning suggestions. This goes well beyond the structured 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?

The description is four dense sentences, each adding unique value: purpose, when to use and alternatives, behavioral constraints, and error behavior. It is front-loaded with the core action and contains no redundant or filler content.

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 complexity, the output schema, and full parameter documentation, the description is complete: it covers purpose, usage timing, explicit alternatives, safety/behavior, and error handling. No essential guidance is missing for an AI agent to select and invoke 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?

The input schema describes all three parameters with detailed semantics, including an enum for language and a note that powershell is more skeletal. Since schema coverage is 100%, the description adds little beyond the schema, 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?

The description opens with 'Emit ready-to-adapt code for one Partner Center scenario in the language you ask for', providing a specific verb and resource. It distinguishes itself from siblings by explicitly naming pc_build_request and pc_get_scenario, and by noting only current REST is emitted, never the archived .NET SDK.

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?

States 'Use this when you want code' and explicitly directs users to alternatives: 'For a structured method/url/headers/body object to send yourself, use pc_build_request; for the underlying facts and gotchas, use pc_get_scenario.' It also sets a clear exclusion with 'Only current REST is emitted — never the archived .NET SDK.'

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, and destructiveHint, and the description adds meaningful context: 'offline, deterministic', the index returned when name is omitted, and the error shape with suggestions for unknown names. No contradiction with 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?

The description is compact and front-loaded, with each sentence serving a distinct purpose: primary function, usage context, sibling alternatives, behavioral notes. No fluff 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?

The tool is simple (one optional parameter) and the description covers all key aspects: what it returns, when to use it, how it behaves with omitted/unknown names, and relationship to siblings. Output schema exists, so return details are already specified.

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 input schema description covers 100% of parameter semantics, including examples, case-insensitivity, and the omit behavior. The tool description reiterates these points but adds little beyond the schema; 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?

The description states clearly that the tool returns accepted values for a Partner Center enum with explanations, and lists common enum names. It distinguishes itself from sibling tools by explicitly pointing to pc_get_resource and pc_build_request for different needs.

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?

Provides explicit when-to-use guidance ('Use this before sending a request body... rather than guessing'), names alternatives (pc_get_resource, pc_build_request), and explains behavior for omitted or unknown names. This is strong direction on selecting the correct tool.

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, but the description adds valuable beyond-annotation context: 'offline' and 'deterministic', plus the insight that the payload shape differs per topic. No contradiction with 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?

The description is tight and front-loaded, using a single sentence for the core purpose followed by usage and a behavioral note. No wasted words, every sentence adds value.

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 simple one-parameter interface and the presence of an output schema, the description fully covers the tool's scope. It explains the topic categories, usage boundaries, and behavioral traits, making it complete for an agent to select and invoke 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% with detailed enum descriptions, so baseline is 3. The description adds the useful note that the payload shape differs per topic, which is not in the schema, justifying a 4.

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 explicitly states the tool returns cross-cutting facts (base URLs, headers, versioning, sandbox, rate limits, national clouds), naming the verb 'Return' and the resource. It distinguishes from siblings by naming pc_get_scenario and pc_auth_guidance as alternatives for specific endpoint and auth topics.

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 explicit usage guidance: 'Use this for questions about the API as a whole' and directly names alternatives for specific endpoints (pc_get_scenario) and authentication (pc_auth_guidance). This makes the when-to-use decision unambiguous.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds highly relevant behavioral details: 'Read-only, offline, deterministic' plus expected behaviors when 'name' is omitted and for unknown names (returning ok:false with suggestions). No contradiction with 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?

The description is compact yet comprehensive. Each sentence earns its place: purpose, usage guidance, alternative tools, behavioral traits, and edge-case behavior. It is front-loaded with the core purpose and structured for quick scanning.

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, rich output schema, strong annotations), the description is complete. It covers all key aspects needed by an agent: what it does, when to use it, how edge cases behave, and how it relates to sibling tools. No important information 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 schema already provides 100% coverage with a thorough description of the 'name' parameter (including case-insensitivity and omission behavior). The tool description does not add any parameter-specific semantics beyond what the schema already states, so the 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?

The description opens with a specific verb+resource ('Return the field dictionary for a Partner Center resource') and lists concrete resource examples. It explicitly distinguishes itself from siblings by naming pc_get_enums and pc_build_request as alternative tools for different needs.

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 clearly states when to use the tool ('understand a payload you received or to work out what a request body needs') and gives explicit alternatives for different use cases ('For the accepted values of an individual field use pc_get_enums, and for a ready-to-fill body skeleton use pc_build_request').

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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=false), the description adds substantial behavior: 'Read-only. Offline and deterministic unless `enrich` is set...' and the unknown-id behavior returning ok:false with suggestions. This goes well beyond what annotations provide and does not contradict them.

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 dense paragraph with no filler words. Every sentence contributes critical information: return contents, usage timing, alternative tools, behavioral caveats, and error handling. The structure front-loads the purpose and then supplies necessary context.

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 complexity and the presence of an output schema, the description covers all necessary contextual aspects: what the tool returns, when to use it, how to get the id, alternative tools, offline/deterministic behavior, enrich side effects, and error response shape. Nothing essential 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 coverage is 100% and both parameters are already described in detail in the schema. The description reinforces the id lookup and enrich effects but does not introduce new parameter semantics beyond what the schema provides, earning the baseline score for high coverage.

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 starts with a specific verb and resource: 'Return the complete verified record for one Partner Center REST operation' and enumerates the exact contents (method, path, auth type, headers, request/response shapes, examples, gotchas, doc link). It clearly differentiates from siblings like pc_list_scenarios and pc_generate_call.

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 states when to use the tool ('once you know the scenario id') and names the exact sources for the id. It also gives explicit alternatives: 'For runnable code in a specific language prefer pc_generate_call; for a request body skeleton prefer pc_build_request.'

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?

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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint; the description adds 'offline, deterministic' and details the ok:false cases (missing both params, unknown code with suggestions). This goes beyond the annotations, informing the agent about side-effect-free, repeatable 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?

Four sentences with no filler; front-loads the core function, then gives alternatives and constraints. 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 two-parameter lookup tool with a rich output schema and strong annotations, the description covers use cases, alternatives, edge cases, and failure modes. No significant gaps remain.

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 both parameters. The description adds the exclusive-or rule that exactly one must be supplied and mentions the precedence and unknown-code suggestions, which are not in the schema. Since the schema is thorough, the extra value is moderate but meaningful.

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 ('Look up') with a clear resource ('Partner Center error') and enumerates the returned fields (meaning, causes, remediation, doc link, scenarios). It explicitly distinguishes from siblings by naming pc_decode_error and pc_diagnose, so the agent knows exactly when this tool is appropriate.

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?

States 'Use this when you already have a clean code' and provides explicit alternatives for raw responses (pc_decode_error) and prose symptoms (pc_diagnose). It also specifies the input constraint (exactly one of code/httpStatus) and the failure behavior, giving clear operational 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?

The description adds meaningful behavioral context beyond the annotations: it is 'read-only, offline, deterministic pattern matching', the snippet is not executed, and nothing is rewritten in place. It also discloses the return contract — always ok:true, with empty `matches` and `unmatched:true` when nothing matches. No contradiction with the readOnlyHint/idempotentHint 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?

The description is four sentences, front-loaded with the purpose, followed by workflow and behavioral guarantees. Every sentence earns its place, and there is no filler or redundant restatement of the title beyond a natural subject line. It is information-dense but still easy to scan.

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 tool with an output schema, the description is complete: it covers why to use it, how to chain it with other tools, what it does and does not modify, and what the empty-result response looks like. The agent has everything needed to invoke it correctly and interpret the outcome.

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 input schema is 100% covered, including details like case-insensitive matching and multiple calls per snippet, so the tool description does not need to add parameter-specific semantics. It does include 'snippet' and 'each one', but those largely repeat what the schema already says. Baseline 3 is appropriate because the schema carries the parameter documentation 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 opens with a specific action — 'Find the archived Partner Center .NET SDK calls in a snippet and map each one to the current REST scenario' — clearly identifying the resource and the transformation. It also distinguishes itself from sibling tools by naming pc_check_auth and pc_generate_call as complementary steps, 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?

It explicitly states when to use the tool ('Use this to port code off the SDK') and describes a workflow with pc_check_auth and pc_generate_call. The alternative tools are named, so an agent can decide whether to run this tool or a sibling. This is exactly the kind of guidance needed for correct tool selection.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: "nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack." This clarifies exactly what the tool does and does not do, going beyond the safety profile implied by annotations. No contradiction with 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?

The description is front-loaded with the core purpose, then efficiently covers usage, alternatives, behavioral constraints, return structure, and follow-up tools. Every sentence adds useful information with no filler. The density is high but not overwhelming; it is appropriately sized for a workflow-planning 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?

Given the tool's moderate complexity, the description covers the full picture: what it returns (goal, steps with key fields, notes), how to use the output (pass scenarioId to pc_generate_call or pc_get_scenario), and the planning-only constraint. The output schema handles detailed return structures, so the description need not restate them. This is complete for an agent to select and invoke 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?

The schema fully covers the single optional customerId parameter with a detailed description of substitution behavior. The tool description itself does not mention this parameter or add any extra nuance beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate, but the description earns no credit for parameter enrichment.

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 starts with a specific verb+resource: "Return the ordered CSP customer onboarding workflow" and lists the exact steps. It explicitly distinguishes itself from sibling tools pc_plan_gdap_onboarding and pc_plan_transfer, making its unique role clear. This is a model of purpose clarity.

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 gives explicit when-to-use context: "Use this to link an existing tenant to your CSP account before you can transact for them." It also names alternatives for other scenarios (admin access via pc_plan_gdap_onboarding, partner transfer via pc_plan_transfer). The "Planning only" note sets expectations that this is not for execution.

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?

Beyond the annotations that already indicate a safe read-only operation, the description adds crucial context: 'Planning only: nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack.' This fully discloses the tool's non-executing nature and resource usage, which is more informative than the annotations alone.

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 dense but every sentence serves a purpose: it states the function, lists the workflow steps, gives usage context, distinguishes from sibling tools, clarifies behavioral guarantees, defines the return structure, and directs next steps. It is front-loaded with the core purpose and contains no redundant or filler phrases.

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 complexity (exposing an ordered workflow with multiple steps) and the presence of an output schema and full annotations, the description fully covers what the tool does, how to use it, what it returns, and how to proceed (pass scenarioId to pc_generate_call). It is complete for an agent to select and invoke 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?

The schema already provides 100% coverage of the single parameter (customerId) with a detailed description including substitution behavior and optionality. The tool description does not add new semantic meaning; it merely restates the placeholder substitution concept already in the schema. Thus, 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?

The description clearly states the tool's function: 'Return the ordered GDAP onboarding workflow' and lists the specific steps involved. It explicitly differentiates from sibling tools by naming pc_plan_csp_onboarding as the alternative for the commercial relationship, making its scope 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 when-to-use guidance: 'Use this when you need granular delegated admin rights over a customer tenant.' It also gives a clear exclusion and alternative: 'for the commercial relationship (invitation + agreement) use pc_plan_csp_onboarding, which is the usual prerequisite.' This fully addresses tool selection.

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?

Beyond the annotations (read-only, idempotent), the description discloses that no credentials are used, no network call is made, and nothing is executed. This is valuable operational context that goes beyond what annotations provide.

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 dense but well-structured; the first sentence gives the core function, followed by usage, safety, output, and next steps. No filler content.

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?

It provides a complete picture: purpose, usage, constraints, output structure, and related tools (pc_generate_call, pc_get_scenario). Combined with the annotations, the agent has everything needed to select and invoke 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?

The schema fully documents the optional customerId parameter with a detailed description (GUID format, substitution behavior, omit to get placeholders). The tool description itself does not add further parameter details, but the schema coverage is 100%, making this acceptable.

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 tool returns an ordered workflow from cart to provisioned subscriptions, listing the phases (build cart, checkout, poll, resolve, confirm). It explicitly differentiates from pc_plan_purchase and pc_plan_subscription_change, 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?

Provides explicit when-to-use ('when a purchase has to be verified rather than assumed') and names alternatives for choosing a purchase and for subscription changes. Also clarifies it's planning-only, not execution.

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 indicate read-only and non-destructive behavior. The description adds valuable context beyond annotations: 'Planning only: nothing is executed, no credentials are used, no network call is made.' This clarifies safety and side-effect-free behavior, consistent with 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?

Every sentence serves a distinct purpose: main function, scope, alternatives, rationale, and safety. No redundant or filler content; well-structured and front-loaded.

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 description covers purpose, usage guidance, alternatives, and safety considerations. With a full input schema and output schema present, all necessary context for an AI agent to select and invoke the tool is provided.

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 parameters are well-documented in the schema. The description only references 'parameters you have to supply yourself' conceptually, adding little semantic detail beyond what the schema already provides.

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 tool's function: 'Given any scenario, return the ordered calls that produce the ids its path needs, plus the parameters you have to supply yourself.' It also distinguishes itself from sibling tools by emphasizing it works for 'every operation in the pack, not just the ones with a hand-written workflow.'

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?

Explicitly provides when-to-use and alternatives: 'For a business sequence and its preconditions prefer the curated planners' and lists all sibling curated planners. It also clarifies the tool's niche: 'This one only resolves parameters, which is why it works everywhere.'

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, destructiveHint=false, idempotentHint=true, and the description reinforces this with additional behavioral facts: 'Planning only: nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack.' This adds context beyond annotations (credential use, network call) and clearly states the planning-only nature, making behavior fully transparent.

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 dense sentence plus a follow-up sentence. It is front-loaded with the purpose, and every clause adds value: it lists workflow steps, distinguishes alternatives, clarifies planning-only scope, and describes return structure. While compact, the density makes it slightly less scannable than the ideal two-sentence structure, but there is no waste, so a 4 is appropriate.

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?

Even though an output schema exists, the description specifies the return shape: 'Returns { goal, steps[] with order/scenarioId/method/path/url/authType/why/keyGotchas/docUrl, notes[] }.' It also covers integration with pc_generate_call, clarifies scope (no network/credentials), and names alternatives. For a planning tool with two optional params and full schema coverage, this 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?

The input schema documents both optional parameters (country and customerId) with 100% description coverage, including examples and substitution behavior. The description itself adds no parameter-specific semantics beyond referencing 'resolved URL' and placeholders, so it does not improve on the schema. 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?

The description opens with a specific verb+resource: 'Return the ordered end-to-end New Commerce purchase workflow' and enumerates the steps (find product, get SKU availability, build cart, check out, resolve subscriptions). It also distinguishes from siblings by naming pc_plan_transfer and pc_plan_csp_onboarding with their respective use cases, 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?

Explicit usage guidance is provided: 'Use this to buy new subscriptions for a customer.' Alternatives are clearly named: 'To move existing subscriptions between partners use pc_plan_transfer, and to link the customer to your account first use pc_plan_csp_onboarding.' It also explains how to chain with pc_generate_call, giving complete when-to-use and when-not-to-use context.

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 description adds meaningful behavioral detail beyond the readOnly/idempotent/non-destructive annotations: no Partner Center credentials are used, no network call is made, and it is a lookup over a bundled scenario pack. It also warns about v1 endpoint retirement, which is valuable operational context. No contradiction with 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?

The description is front-loaded with the primary action and purpose, then layers in caveats, return format, and related-tool guidance. It is longer than a minimal description but every sentence adds value; the only minor inefficiency is some redundancy in the 'Planning only' clarification.

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 the output schema exists and the description already covers purpose, usage boundaries, behavioral constraints, output structure, and next-step actions, the description is complete for an agent to select and invoke this tool correctly. No major operational gaps remain.

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 only one parameter, customerId, and the input schema already fully documents it, including placeholder substitution behavior and omission semantics. The tool description itself does not add parameter-level detail, so the baseline of 3 applies due to 100% schema coverage.

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 opens with a specific verb and resource: 'Return the ordered invoice reconciliation workflow for a billing period' and enumerates concrete steps (locate invoice, read totals, pull line items, download statement). It clearly differentiates from sibling planning tools by naming its exact domain (billing and revenue reconciliation).

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?

Explicitly states when to use it: 'Use this for billing and revenue reconciliation.' It also provides an exclusion, 'Planning only: nothing is executed,' and points to an alternative tool for related concerns: 'call pc_whats_new for the cutoff dates.' It additionally tells the agent how to proceed with returned steps via pc_generate_call/pc_get_scenario.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds specific behavioral details: 'nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack.' It also explains the internal plan structure (reads subscription first, states precondition, performs, confirms). This significantly exceeds annotation-only information.

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 well-structured sentences. The first sentence states the core purpose and operations. The second gives usage and alternatives. The third clarifies constraints and return structure. Every sentence adds value, and the content is front-loaded with the primary function.

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?

Despite the tool's complexity, the description covers the full context: what it does, how to choose it (with alternatives), safety/profile (no execution, no credentials, no network), the return shape ({ goal, steps[], notes[] }), and how to proceed (pass scenarioId to pc_generate_call or pc_get_scenario). The output schema is also present, so the description is thoroughly 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?

The input schema already provides 100% coverage with descriptions for both parameters, including the enum values and the optional customerId placeholder substitution. The tool description itself does not add meaning beyond the schema—it mentions the return steps but not the parameters. Baseline of 3 is appropriate when schema fully documents parameters.

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 tool returns an ordered call sequence for one subscription lifecycle change, and enumerates the specific operations (increase-seats, decrease-seats, upgrade, etc.). It explicitly distinguishes from sibling tools by pointing to pc_explain_lifecycle for choosing an operation, pc_plan_purchase for new purchases, and pc_plan_order_lifecycle for order-side planning, 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?

It provides explicit guidance: 'Use pc_explain_lifecycle to find out WHICH operation is available; use this to find out HOW to run it.' It also clarifies planning-only nature and directs alternative tools for purchase and order lifecycle. The description even notes to pass a scenarioId to pc_generate_call for runnable code, giving clear next steps.

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 description discloses that the tool is planning-only, executes nothing, uses no Partner Center credentials, and makes no network call — a lookup over the bundled scenario pack. This goes well beyond the annotations (readOnly, idempotent, non-destructive) by explaining the actual behavioral mechanics. It also specifies the return format and how to use the returned scenarioId with other tools, providing rich behavioral 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?

The description is efficient and well-structured: it opens with the core action, then usage context, then exclusions, then safety caveats, then return format and follow-up tools. Every sentence adds essential information without redundancy. It is somewhat longer than two sentences, but each sentence earns its place, and the structure aids comprehension.

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 role as a planning/lookup tool, the description is complete: it covers purpose, usage criteria, behavioral safety, return value structure, and integration with pc_generate_call and pc_get_scenario. The output schema exists, so return details need not be exhaustively repeated. Combined with the detailed schema and annotations, the description leaves no critical gaps.

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% and the schema already provides a thorough explanation of the optional customerId parameter, including a GUID example, substitution behavior, and what happens when omitted. The description itself does not add parameter-level information, but the baseline of 3 is appropriate because the schema carries the full burden and does so effectively.

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 tool returns an ordered workflow for a New Commerce transfer, with specific verb 'Return' and resource 'ordered New Commerce transfer (billing-ownership change) workflow'. It also lists the steps (create, poll, verify), making the tool's purpose unmistakable. It explicitly distinguishes from siblings like pc_plan_csp_onboarding and pc_plan_purchase, removing any ambiguity about when to use each.

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 gives explicit usage context: 'Use this when a customer is moving to a new partner of record.' It also names two alternative tools for different scenarios (first-time link-up and buying new subscriptions), providing clear 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.

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 crucial context beyond that: 'nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack.' This fully characterizes the tool's behavior with no contradiction.

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 compact yet information-dense. It front-loads the primary purpose, then covers usage, safety, output structure, and follow-up actions in a logical flow. Every sentence earns its place with no redundant 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?

Tool complexity is moderate, but the description covers the goal, return object shape, ordering of steps, and downstream integration (pc_generate_call, pc_get_scenario). The output schema exists, so not explaining return fields is acceptable. Annotations and schema fully complement the description.

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 the baseline is 3. The description adds meaningful semantics for the single customerId parameter: substituting it makes the plan 'ready to run' while omitting yields 'generic plan with placeholders.' This goes beyond the schema's basic type/format info, meriting a 4.

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 and resource: 'Return the ordered workflow for removing a user from a customer tenant' and details the safe order (licenses, seats, roles, delete). It clearly distinguishes from siblings by naming the inverse tool (pc_plan_user_onboarding) and a separate concern (cancelling subscriptions).

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?

States explicitly when to use: 'Use this to decommission a person without stranding licenses.' Provides alternatives and exclusions: 'The inverse is pc_plan_user_onboarding; cancelling the subscriptions themselves is a different concern.' This is model usage 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description explicitly states 'nothing is executed, no Partner Center credentials are used, and no network call is made — it is a lookup over the bundled scenario pack.' This adds operational context that is not captured by the annotations, such as the absence of network I/O and credential usage. No contradictions with 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?

The description is information-dense but every sentence contributes: purpose, usage context, behavioral guarantees, return format, and tool relationships. It is front-loaded with the primary function and uses punctuation to pack a lot of value without being redundant. No filler or tautology.

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 description provides a full picture of what the tool returns (goal, steps[], notes[]), the structure of each step, and how to continue with pc_generate_call or pc_get_scenario. Combined with the output schema (present), the tool's behavior, limitations, and integrations are completely specified. The description is self-sufficient for an AI agent to select and invoke it appropriately.

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% for the single optional parameter customerId, with full detail about placeholder substitution already in the schema. The tool description does not add new information about this parameter; it focuses on the output structure and cross-references. Since the schema fully covers the parameter, a baseline score of 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?

The description opens with a specific verb and resource: 'Return the ordered workflow for onboarding a user inside a customer tenant' and enumerates the steps (pick SKUs, create account, assign licenses, grant roles, verify). It also explicitly distinguishes itself from siblings by stating it is 'unrelated to buying subscriptions' (pc_plan_purchase) and names the reverse tool (pc_plan_user_offboarding). This makes the purpose unmistakable and differentiates it from other planning tools.

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 gives clear usage context: 'Use this for people-level provisioning.' It also provides exclusions and alternatives: 'It is unrelated to buying subscriptions — for that use pc_plan_purchase — and the reverse direction is pc_plan_user_offboarding.' Additionally, it clarifies that this is planning-only, not execution, which sets expectations for when to invoke this tool vs. a generation tool.

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?

Beyond annotations, the description discloses non-determinism ('results are not deterministic'), potential slowness, possible empty result with a note, retry safety, and no credential requirements. This enriches the readOnly/openWorld annotations with realistic failure and operational 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?

The description is concise, with no fluff. Each sentence contributes purpose, usage guidance, internet caveats, or return format. It is front-loaded with the core purpose.

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?

Covers purpose, when to use, behavioral traits, parameter nuances, and return shape ({ excerpts[], note }). Even though an output schema exists, the description summarizes it helpfully. No significant gaps given the tool's complexity.

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 already covers both parameters with descriptions, but the description adds 'Partner Center is prepended automatically, so do not repeat it' and notes that error codes/endpoint paths work as queries, plus explains topK omission behavior. This goes beyond the schema's baseline.

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 the tool searches 'live Microsoft Learn Partner Center developer documentation' and returns 'matching excerpts', using a specific verb and resource. It clearly distinguishes from offline curated siblings by emphasizing 'live'.

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?

Explicitly instructs to try pc_list_scenarios / pc_get_scenario / pc_lookup_error first, and to use this tool as a fallback when the curated pack has no answer. This names concrete alternatives and gives both when and when-not to use.

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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses that the tool is offline and deterministic, never sends the request, and recommends placeholder tokens. It also notes the limitation that an empty result does not guarantee success, which is valuable honesty about the tool's coverage.

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 dense yet well-structured: it opens with the main purpose and checks, then gives usage context and alternatives, then safety behavior and limitations. Every sentence earns its place, and the length is appropriate for a tool with this complexity.

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 output schema and annotations, the description covers all necessary context: purpose, when to use, key behaviors, safety, and limitations. It is sufficient for an agent to select and invoke the tool correctly among many siblings, with no major gaps.

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 a baseline of 3 applies. The description adds meaning by linking parameters to the checks performed (e.g., omitting headers skips header checks, omitting authType skips the app-only check, cloud influences sovereign-cloud findings), which goes beyond the individual field descriptions.

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 identifies the tool as a linter for an already-written Partner Center REST request, enumerating specific validations (method/path, headers, auth audience, app-only support, cloud host). It explicitly contrasts with sibling tools pc_build_request and pc_decode_error, making the tool's unique role unmistakable.

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 states precisely when to use the tool: to catch mistakes before sending or to explain a failing call. It also names alternatives for adjacent tasks (building a request with pc_build_request, decoding a response with pc_decode_error), providing clear decision 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, idempotentHint, and openWorldHint=false, but the description adds valuable behavioral context: it is 'offline, deterministic — sourced from the bundled pack' and thus 'only as current as the pack's last refresh rather than a live feed.' This goes beyond annotations and helps set accurate expectations about data freshness.

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 comprehensive but every sentence earns its place: it lists content, states usage, names an alternative, and discloses data-source characteristics. It is front-loaded with the tool's core function and does not include filler or redundant wording.

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 output schema exists, return values need no explanation. The tool has only one optional parameter, and the description covers purpose, usage, alternatives, and behavioral limitations. It is complete for a list-oriented tool with strong annotations.

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 description covers the status parameter fully (enum values and 'Omit to get every item'), so the baseline is 3. The tool description does not add further parameter-specific meaning, but it does not need to given the schema's high coverage.

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 resource ('Partner Center API deprecations and retirement deadlines'), enumerates concrete examples, and distinguishes itself from siblings by explicitly referencing pc_check_auth for code-level checks. This clearly communicates what the tool does and how it differs from related tools.

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?

Explicitly states when to use the tool ('before committing to an endpoint or auth mechanism', 'to explain why something that used to work has stopped') and points to an alternative (pc_check_auth) for specific code checks. This is strong usage guidance with clear context and exclusions.

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