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

No annotations exist, so the description must carry the behavioral burden. It flags 'EXPERIMENTAL' but says nothing about overwrite semantics, permissions, whether it pushes to the portal, or any side effects. The mention of 'verify with cs_pack and in the portal after push' implies a local-file workflow, but this is understated and could mislead an agent into thinking the flow is live immediately.

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?

Single sentence, front-loaded with the experimental warning, then states the core action. It packs a lot of information without fluff, though the format references are dense. It earns a 4 for efficiency, not for clarity of usage.

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 an 8-parameter tool with nested objects and no output schema, the description is far from complete. It doesn't explain how inputs/actions/outputs are structured, what the response is, or how overwrite behaves. The verification step is useful but not a substitute for usage semantics. An agent would need to inspect the schema and possibly sibling tools to call 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 description coverage is only 38%, and the description does not compensate. It only references 'Name' implicitly. Inputs, outputs, actions, overwrite, and workspace are left undefined. The schema descriptions for addTool and workspace are present but minimal, and the description adds no further meaning for the array/object 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 states a specific verb ('write'), resource (workflows/<Name>/metadata.yaml + workflow.json), and the exact trigger ('when an agent calls the flow') and response. This clearly distinguishes it from siblings like cs_create_flow or cs_build_flow_definition, which operate on live flows or build definitions. The experimental tag is upfront.

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention that it creates local scaffold files vs. modifying an existing flow, nor does it compare with cs_update_flow or cs_create_flow. The only hint is the verification step, but that's post-action, not a selection criterion.

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 some behavioral nuances beyond a generic 'add' operation: for kind 'files' it states that documents are copied into knowledge/files for upload on a future push, and for 'graph-connector' it specifies using an environment variable. It does not mention permissions, reversibleness, logged side effects, or how the YAML is persisted/modified. Since annotations are empty, the description carries the full burden and only partially fulfills it, so a 3 is appropriate.

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

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

The description is a single sentence that efficiently fronts the core action (Add knowledge as YAML) and packs specific constraints into a compact caveat. There is no repetition of schema content and every clause it joists against the actual parameter values (public-site, sharepoint, etc.). It is appropriately sized, holds zero filler, and places the most actionable information at the beginning.

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 12-parameter tool with no annotations and no output schema, the description does not explain or prepare the agent for each parameter's purpose, the actual side effects of invocation, or any other prerequisites. It covers only the kind parameter semantics plus a few behavior notes, leaving the agent with significant unknowns (e.g., what 'site' expects, what 'overwrite' affects, how 'includeSubPages' works, when the YAML files are written, etc.). Therefore it falls short of the level of completeness needed for an agent to reliably invoke the tool in varied scenarios.

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

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

With only 25% of parameters described in the schema, the description helps to enrich the meaning of the 'kind' parameter (e.g., 'public-site' is a Bing-scoped website with max 2 path levels), which directly clarifies the enum keywords. However, it does not clarify or map many other parameters like 'site', 'overwrite', 'includeSubPages', 'contentSourceDisplayName', or 'connectionEnvironmentVariable', so the added meaning is concentrated on just one dimension and only partly compensates for the overall low 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 clearly states the tool's verb (Add), resource (knowledge), and the format ('as YAML'), and differentiates from siblings like cs_edit_knowledge by defining it as an add operation. It also enumerates the four supported 'kind' values with specific constraints, making the tool's scope 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 provides explicit when-not guidance by stating that Dataverse, AI Search, and SQL knowledge are portal-only and therefore cannot be used with this tool. It also gives usage constraints for each kind (e.g., 'max 2 path levels', 'via environment variable'), which clearly informs when this tool is appropriate. It does not name a specific alternative tool for editing existing knowledge sources, so a single 5 is not warranted, but the context is strong and includes an explicit exclusion.

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?

With no annotations provided, the description correctly takes on the burden of disclosing behavioral traits. It explicitly states that the tool mutates a live environment and that confirm: true is required for an actual change, otherwise it is a dry run. This is a critical, non-obvious behavior that is well communicated.

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 concise sentences with no fluff. The primary purpose is front-loaded, followed by the command invocation and the critical mutation caveat. Every sentence adds value, and the structure is clean and 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?

Given the complexity (11 parameters, no output schema, no annotations), the description covers the essential operational behavior (mutation, dry-run, command). However, it omits information about return values or success/failure indicators, which would be useful given the absence of an output schema. It is adequate but not 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 provides 100% coverage of all 11 parameters with clear descriptions, so the baseline is 3. The description adds minimal extra meaning beyond the schema—it restates the component identification method ('by schema name or id') and repeats example type codes already present in the schema. It does not significantly enhance understanding of the 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 action (add an existing component) and the resource (an unmanaged solution), with a list of example component types. It is specific enough to identify the tool's purpose, though it does not explicitly contrast it with sibling add-tools like cs_add_solution_reference or cs_add_solution_license.

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

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

The description explains what the tool does but gives no guidance on when to use it versus alternative add-solution tools. It mentions running the pac command and the requirement for confirm, but these are operational details, not usage context. There is no 'when to use' or 'when not to use' information.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds useful context: 'Local file change only' (non-destructive to remote state) and 'Runs pac solution add-license with the active pac auth profile' (delegation and auth dependency). It does not disclose failure behavior, reversibility, or what happens after the files are attached, which matters for a file-mutating tool with no annotation safety hints.

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 short sentences with zero waste: purpose is front-loaded, followed by the cwd prerequisite, the local-only guarantee, and the pac delegation detail. 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?

With 6 parameters, no output schema, and no annotations, the description covers purpose, prerequisite, and behavioral scope well. The main gap is that it does not disclose the return value (no output schema exists, so the description would need to state it), nor the effect of the background parameter on jobId behavior. Otherwise it is complete for an attachment-style command.

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 schema already documents all six parameters including the CSV column layouts for planMappingFile and planDefinitionFile. The description reinforces the cwd requirement ('Run in the solution project folder') but adds little beyond the schema. Baseline 3 is appropriate given the high 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 names a specific verb and resource: 'Attach license plan definition and mapping CSV files to a solution project (ISV licensing).' This clearly differentiates it from sibling tools like cs_add_solution_component and cs_add_solution_reference, which target different artifact types within a solution. The title reinforces the same resource.

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 a clear usage condition — 'Run in the solution project folder (cwd)' — and scopes it to ISV licensing. However, it does not explicitly name alternatives or state when NOT to use this tool versus siblings such as cs_add_solution_component, cs_add_solution_reference, or cs_pack_solution. The context is implied rather than stated as exclusions.

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?

With no annotations, the description carries the burden, and it discloses the key behavioral traits: it modifies a local .cdsproj file only, must be run from the solution project folder, and shells out to pac solution add-reference. It does not detail error behavior or exact file changes, but the safety scope and execution model are clear.

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 short sentences, each supplying useful information: purpose, required working directory, side-effect scope, and underlying command. No redundant restatement of the title or schema.

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 no output schema and no annotations, the description covers the main behavioral contract (local file change, folder requirement, command used) and the schema covers all parameters. It could add the shape of the command's result or failure modes, but nothing essential for invoking the tool is missing.

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

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

Schema description coverage is 100%, so the baseline applies: the schema already documents cwd, path, profile, background, and timeoutSeconds. The description adds little beyond noting the cwd requirement and active profile, so no extra parameter credit is warranted.

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

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

The description names a specific verb and resource: reference another project (plug-in, PCF, ...) from a .cdsproj so it is packed into the solution. This is clear and aligns with the title, but it does not explicitly differentiate from closely related siblings such as cs_add_solution_component, so it stops short of 5.

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

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

It gives actionable context: run it in the solution project folder (cwd), it is a local file change only, and it invokes the pac add-reference command with the active pac auth profile. It doesn't name alternatives or exclusions, but the context is concrete enough for an agent to know the intended invocation.

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?

With no annotations present, the description carries the full burden and does substantial work: it discloses that the tool writes a connection-reference stub, returns a portal step for connector/MCP types, checks operationId against a cached catalog, and auto-fills required inputs unless inputs are given. It does not state whether overwrite is destructive or what happens on validation failure, but the disclosed behaviors go well beyond a bare 'Add a tool'.

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

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

The description is dense but organized as a type-by-type list, which is appropriate for an 18-parameter tool. It front-loads the core artifact and then groups related information. It is long, but nearly every clause carries routing or behavioral information; only minor redundancy exists between the title and the first sentence.

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 18-parameter tool with no output schema and no annotations, the description covers the main decision axes: which type to choose, which identifiers to supply, and the connection caveat. It does not explain the return value or the portal step in detail, and it leaves outputs/overwrite semantics to the schema, but the essential calling context is present.

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

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

Schema coverage is 56%, and the description compensates for the gap by explaining the meaning of type-specific identifiers (connectorId, operationId, aiModelId, botSchemaName, gptComponentSchemaName) and the inputsFromCatalog default. It does not elaborate on outputs, overwrite, or modelDescription, but the type-routing explanation adds real value 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 concrete artifact ('Create actions/<name>.mcs.yml') and then enumerates every supported type with its required identifiers, which fully disambiguates this from sibling tools like cs_add_flow, cs_add_topic, and cs_edit_tool. The verb 'Create' plus the explicit file target makes the tool's function 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 gives per-type selection guidance ('type 'connector': ... use cs_list_connectors / cs_describe_connector to find them', 'type 'prompt': ... cs_list_prompts'), tells when inputs are auto-filled from the catalog, and warns that connector/MCP tools need a portal-authorized connection. This is explicit when-to-use and how-to-route 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?

With no annotations, the description adds some behavioral context: it says it 'Validates the result' and gives a workflow cue via 'Push to apply.' However, it does not disclose side effects such as overwrite behavior, workspace path resolution, what happens when validation fails, or whether the tool itself pushes changes or only stages 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 gets to the point quickly and each clause adds information: the resource being created, the spec shape, validation, and the push action. It is slightly dense because of the long node-type list, but there is no filler or repetition holding back.

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 has 8 parameters including a large action schema, no output schema, and no annotations. The description does not explain expected return values, failure modes, whether the push must be done with a separate tool, or workspace/overwrite semantics, so a caller must guess or rely entirely on the schema for an invoke.

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 description explains trigger phrases vs a system trigger and lists the expected action node types, which the role of the 'actions' array at a high level. But with only 38% schema coverage it doesn't compensate for undocumented concerns like 'overwrite', 'priority', 'description', or the workspace parameter, and the node list is incomplete (missing card, transfer, endConversation) even though the schema supports them.

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 precise verb and resource ('Create topics/<name>.topic.mcs.yml') and names the main ingredients of the declarative spec. It clearly distinguishes the creation function from siblings like cs_edit_topic by using 'Create' and mentioning the file path pattern.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The tool name and 'Create' imply new-topic use, but the description does not tell the agent when to prefer this over cs_edit_topic, cs_add_trigger, or other mutation tooling, and it omits final state requirements like when a push is needed.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that a trigger file is created, but does not mention side effects, prerequisites such as whether the cloud flow must already exist, what happens on overwrite, or whether the operation is reversible. This is a significant gap for a mutation tool.

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

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

The description is a single, compact sentence with no filler. It front-loads the file-creation action and then adds the key integration detail about WorkflowExternalTrigger. Every word 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?

Given the lack of annotations, absence of an output schema, and sparse schema documentation for most parameters, the description is too minimal to be complete. It does not cover behavior around overwrite, workspace resolution, required prerequisites, or return values. An agent would likely need to open the schema or guess about important edge cases.

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 only 20%, so the description must compensate for the undocumented parameters. It does add meaning for 'name' by showing it becomes part of the file path, and for 'flowId' by indicating it references the cloud flow. However, overwrite and description remain completely unexplained, leaving the compensation incomplete.

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 that the tool creates a trigger file named trigger/<name>.trigger.mcs.yml and associates it with a cloud flow via WorkflowExternalTrigger. This is a specific verb-resource pair and makes the tool's core function clear. However, it does not explicitly distinguish itself from sibling tools like cs_add_flow or cs_add_tool, so it falls short of a 5.

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

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

The phrase 'pointing at a cloud flow that starts the agent (WorkflowExternalTrigger)' implies the tool should be used when an event trigger backed by an external cloud flow is needed. There is no explicit guidance about when not to use it or which sibling alternative might be more appropriate, but the intended context is reasonably inferable.

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?

No annotations are provided, so the description carries the full burden. It discloses the file creation and component type, but does not mention whether overwrite behavior is default, what happens if the file exists, whether the variable is immediately available, or any side effects. The 'overwrite' parameter hints at behavior but the description itself doesn't explain it.

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 sentence that is concise and front-loads the key action and resource. It earns its place by specifying the exact file path and component type, though it could add a bit more context without becoming verbose.

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 6 parameters, no output schema, and no annotations, the description is too sparse. It doesn't explain the meaning of key parameters like 'overwrite' and 'aiVisibility', doesn't describe return values or success/failure behavior, and doesn't clarify the workspace context. An agent would need to infer too much to use this 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?

Schema description coverage is only 17%, so the description must compensate, but it only explains the 'name' parameter via the file path template. The 'overwrite', 'workspace', 'description', 'aiVisibility', and 'defaultValue' parameters are not explained in the description, and the schema provides minimal descriptions for them.

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 ('Create') and resource ('variables/<name>.variable.mcs.yml') and identifies the component type (GlobalVariableComponent) and scope (conversation). It is clear what the tool does, though it doesn't explicitly distinguish it from sibling tools like cs_add_topic or cs_add_tool beyond the resource type.

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 no guidance on when to use this tool versus alternatives, no prerequisites, and no context about when a global variable should be created this way. The file path implies it operates within a workspace, but no explicit usage conditions are stated.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states that the tool 'Changes tenant configuration' and 'Mutates a live environment,' and that confirm:true is required to actually perform the change, otherwise it returns a dry run. It also names the underlying command ('pac admin add-group') and the use of the active profile. This is transparent about mutation and the dry-run behavior. It could add detail on reversibility or side effects, but the key behaviors are well disclosed. The repetition of confirm:true is minor.

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 two sentences, front-loaded with the primary purpose and effect, then the confirm requirement, then the implementation detail. It is concise and avoids fluff. The only redundancy is stating confirm:true twice, which is slightly repetitive but not harmful. Overall, it is well structured and 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 mutation tool with 7 parameters (1 required) and no output schema, the description covers the essential operational context: what it does, the effect on the environment, the confirm requirement, and the underlying command. It does not mention prerequisites like the existence of the environment group or that the environment must be specified, but the schema clearly marks environmentGroup as required and environment as optional. It also does not describe return values, but no output schema exists. The description is sufficiently complete for an agent to call it correctly, though it could benefit from noting that the group must already exist.

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 does reinforce the meaning of the confirm parameter by stating it is required for actual changes and that without it the tool is a dry run, which aligns with the schema. It also mentions 'active pac auth profile,' which matches the profile parameter's default behavior described in the schema. However, the description adds little new semantic meaning beyond what the schema already documents, so a 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 action: 'Put an environment into an environment group, which applies that group's rules to it.' This uses a specific verb (put/add) and a precise resource (environment into environment group). It distinguishes the tool from siblings like cs_admin_list_environment_groups by defining the mutation effect. No ambiguity about what the tool does.

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 context that this is a tenant configuration change and a live-environment mutation, and it stresses the confirm:true requirement for actual changes (with a dry run otherwise). However, it does not explicitly compare with alternative tools or state when to use this vs. another admin tool. Since there is no direct sibling that removes from a group or lists groups, the guidance is implicit rather than explicit. The confirm requirement is a clear usage instruction, but broader selection guidance is missing.

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?

With no annotations, the description carries the full burden. It explicitly discloses that the tool mutates a live environment, requires confirm: true, and performs a dry run otherwise. It also reveals the underlying pac command and profile usage, giving clear behavioral expectations.

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 brief and front-loaded with the purpose and critical mutation warning. However, it is redundant: it repeats the same confirm requirement twice ('Changes a live environment...' and 'Mutates a live environment...'), which could be condensed into one sentence.

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 tool with 12 parameters and no output schema, the description covers essential context: purpose, mutation risk, confirm requirement, and the underlying command. Parameter details are handled by the schema, and return values are not specified, which is acceptable. It omits alternative tool guidance but is otherwise complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about the confirm flag and dry-run behavior but does not significantly enhance the schema's parameter descriptions. The underlying command is mentioned, but individual parameters are well documented already.

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?

Clearly states the tool gives an Entra group a security role in an environment via a Dataverse team. It specifies the exact action and resource, and distinguishes from sibling user-assignment tools by focusing on groups. Not tautological or vague.

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 implies usage for group-based role assignment and notes the confirm requirement for live changes, but does not explicitly mention alternatives or when not to use this tool. It lacks routing to sibling tools like cs_admin_assign_users.

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?

With no annotations provided, the description must disclose behavioral traits. It clearly states the tool changes a live environment and requires confirm: true to execute, and that without confirm it is a dry run. This is repeated for emphasis. However, it does not disclose other potential behaviors such as whether existing role assignments are overwritten, error handling, or side effects beyond the mutation. The core destructive nature is disclosed, but the description is minimal.

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 short (two sentences) but redundant: the confirm requirement is stated twice in almost identical terms. It also includes a note about the pac auth profile which, while useful, is not essential to the core action. The structure is acceptable but could be tightened by removing duplication.

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 complex (10 parameters, mutation, no output schema, no annotations). The description covers the critical safety aspect (confirm requirement) but omits many details an agent might need: return format (no output schema), behavior on invalid user/role, interaction with environment parameter, and differentiation from bulk assignment. It is not fully adequate for a mutation tool of this 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 coverage is 100%, so the schema already documents all parameters. The description does not add any semantic detail beyond the schema; it only mentions 'user' and 'role' implicitly. It does not clarify parameter relationships, defaults, or specific formats beyond what the schema provides. 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 a clear action: 'Give a user (or an application user) a security role in an environment.' It specifies the resource (security role) and the target (user/application user) in an environment, and distinguishes itself from the sibling 'cs_admin_assign_users' by implying singular vs. bulk assignment. The mention of running 'pac admin assign-user' adds specificity.

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 no guidance on when to use this tool versus alternatives like cs_admin_assign_users. It notes that it mutates a live environment and requires confirm, which is a caution but not a usage guideline. It does not mention any exclusions or conditions that would route an agent to a different 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?

No annotations are provided, so the description carries the full burden. It clearly states this is a mutating operation ('Changes a live environment: requires confirm: true'), explains the dry-run behavior without confirm, notes that rows are independent (errors don't abort remaining rows), mentions the single approval mechanism, and warns that it runs as an admin account requiring a specific profile. It also discloses that it is unverified against a live tenant, which is a critical trait. This is exemplary given zero annotation support.

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 and informative, covering all critical aspects in a single paragraph. Every sentence serves a purpose: purpose, difference from siblings, dry-run behavior, error handling, mutation requirement, profile handling, alternative tool preference, and verification status. It is front-loaded with the main purpose and usage, and the length is appropriate for the tool's complexity (8 parameters, multiple behavioral nuances). No fluff or repetition.

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

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

Despite having no output schema and 8 parameters, the description covers everything an agent needs to call this tool effectively: the two input methods (csv and assignments), the confirm requirement, background execution for long operations, profile handling, and the alternative tool. It also mentions error behavior and dry-run. The only minor gap is the exact return format of the dry-run plan, but the description says 'you can read the whole thing before any of it happens', which is adequate. Given the tool's complexity, this is remarkably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds valuable context beyond the schema: it explains the CSV header format (user/upn/email, roles/role), how multiple roles are separated, and that users can accumulate roles across rows. It also clarifies the 'confirm' flag's role in making actual changes and the 'background' flag's purpose in avoiding MCP timeout issues. This goes well beyond the schema descriptions and helps the agent correctly construct input.

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

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

States a specific verb ('assign'), resource ('security roles'), and recipient ('roster of users'), and clearly distinguishes itself from the sibling cs_admin_assign_user (single user) and cs_admin_assign_group (group-based). The description explicitly mentions 'many users' and 'one environment', making the 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?

Explicitly contrasts with cs_admin_assign_group (when the roster is a group) and mentions when to use it. It also provides guidance on the confirm flag (dry run vs live), how to handle large rosters (background), and the need to set the admin profile. The description says 'Prefer cs_admin_assign_group when the roster is really a group' and explains the benefit, leaving no ambiguity about when to use this 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?

Given no annotations, the description carries the burden and does well: it discloses mutation of a live environment, the confirm requirement, the dry-run fallback, and that it runs pac admin backup with the active pac auth profile. The main downside is duplicating the same mutation warning rather than adding further behavioral detail such as impact or output.

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?

Front-loaded with the core purpose, but it contains redundant phrasing: 'Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise)' say roughly the same thing. One sentence could be removed without losing information.

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

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

With 7 parameters fully described in the schema and no output schema, the description adds the essential manual-vs-file backup distinction, the underlying command, and the critical confirm/dry-run behavior. It is complete enough for an agent to call the tool correctly, though return behavior is only hinted at via dry-run wording.

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 the baseline is 3. The description mostly reinforces what the schema already documents about confirm and profile, adding only the underlying pac admin backup command context. It doesn't meaningfully clarify label, environment, background, or timeout beyond the schema.

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

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

States a specific action: taking a manual backup of an environment, and immediately contrasts it with the file backup that cs_backup_tenant writes. This makes the tool's purpose unambiguous and differentiates it from a closely named sibling.

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

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

Clearly tells the agent this is the platform backup, not cs_backup_tenant's file backup, and explains the confirm/dry-run behavior. It doesn't explicitly enumerate when not to use it relative to all backup-related siblings, but the primary alternative is named and the usage context is clear.

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?

With no annotations, the description carries the full burden and does so well: it discloses the destructive nature ('Everything in the target is replaced'), the confirm safety gate, the dry-run default, that it mutates a live environment, and the underlying command/auth mechanism. It stops short of documenting async/background termination or failure behavior.

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

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

The description is short and front-loads the core action, but it is redundant: 'requires confirm: true' appears twice, and the final sentence 'Mutates a live environment' largely overlaps with 'Everything in the target is replaced.' Two of the three sentences could be merged without losing information.

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

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

The safety-critical context is well covered: destructive scope, confirm gating, dry-run behavior, and execution mechanism are all stated. However, with 12 parameters, no output schema, and no description of what the call returns (e.g., status message, jobId, or async behavior), an agent is left guessing about the result contract.

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 and the schema already documents all 12 parameters. The description reinforces the confirm parameter's role ('requires confirm: true') but adds no parameter-level meaning beyond what the schema 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 states a specific verb and resource: 'Copy a source environment onto a target environment,' plus the defining consequence 'Everything in the target is replaced.' This clearly identifies the action and makes it distinguishable from admin siblings like delete, reset, or backup, though it does not explicitly name a sibling or contrast condition.

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 operational guidance: to actually mutate you must pass confirm: true, otherwise it is a dry run, and the operation runs via 'pac admin copy' with the active pac auth profile. However, it never states when to choose this tool over alternatives (e.g., cs_admin_reset_environment or cs_admin_restore_environment) or any exclusions.

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?

With no annotations provided, the description carries the full transparency burden. It discloses tenant capacity consumption, that the tool mutates a live environment, the dry-run behavior without confirm, and reliance on the active pac auth profile. This is strong behavioral disclosure beyond the schema.

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

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

The description is short and front-loaded with the core purpose. The only structural weakness is the duplicated 'requires confirm: true' clause appearing in both sentences, which makes it slightly less crisp than it could be.

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 high-complexity mutation tool with no annotations and no output schema, the description covers the essential operational context: side effects, safety switch, dry-run mode, and auth profile. Return shape is not described, but that is an acceptable gap given the detailed input schema and clear behavioral warnings.

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 17 parameters, so the baseline is 3. The description adds useful context about capacity consumption and the underlying pac admin create command, plus the profile behavior, but the confirm requirement is already accurately described in the schema. It does not substantially deepen semantics for most 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 states a specific verb and resource: 'Create a Dataverse environment in the tenant.' It also names the underlying command ('pac admin create'), which clearly distinguishes it from the admin delete, reset, copy, and restore sibling 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 creation context is clear and the description provides a critical usage prerequisite: confirm: true is required to actually mutate a live environment, otherwise it is a dry run. It does not explicitly name alternatives or exclusionary conditions, but the purpose is unambiguous enough for an agent to select it correctly.

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?

With no annotations present, the description carries the transparency burden. It clearly states that the tool mutates a live environment, requires confirm: true to actually change it, and otherwise performs a dry run. It also exposes the underlying command and the use of the active pac auth profile. It does not cover auth requirements or failure behavior, but the key mutation/dry-run behavior is well disclosed.

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 only three sentences, but the second and third sentences are near-duplicates: both state that the tool mutates a live environment and requires confirm: true. This redundancy means not every sentence earns its place, and the structure could be tightened into one or two concise sentences.

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 has no annotations and no output schema, and it is a mutating admin command, so the description carries extra responsibility. It does explain the core use case, mutation behavior, the confirm parameter, and the auth profile context. However, it omits prerequisites such as required admin permissions and does not describe what the dry-run output looks like or how success is reported.

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 schema already documents all eight parameters thoroughly. The description adds some operational context for confirm and profile behavior, but it mostly repeats what the schema already conveys and does not materially enrich 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 names a specific operation: registering an Entra application and assigning it an application user with a security role. It also clarifies the intended purpose as 'the headless identity a pipeline signs in as,' which differentiates it from sibling tools like cs_admin_register_application. The underlying command is named, leaving little ambiguity about what the tool does.

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

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

The phrase 'the headless identity a pipeline signs in as' implies the primary use case, and the confirm/dry-run requirement gives an operational precondition. However, there is no explicit guidance about when to prefer this tool over related sibling tools such as cs_admin_register_application or cs_admin_list_service_principals, and no mention of when not to use it.

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?

No annotations are provided, so the description carries the full burden. It discloses the irreversible nature, the requirement for confirm, and that it runs 'pac admin delete' with the active profile. This is strong behavioral disclosure for a destructive operation. It doesn't mention backup retention details beyond 'platform's own backup retention', which is a minor gap.

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 earning its place: the first defines the scope, the second emphasizes irreversibility and confirm, the third ties it to the underlying command. It is front-loaded with the most critical info about destructiveness and confirm flag.

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 destructive nature and no output schema, the description provides enough for an agent to understand the critical requirements: confirm is mandatory, irreversible, and runs pac admin delete. It could mention the output or potential errors, but the complexity is moderate and the key safety aspects are covered.

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 coverage is 100%, so all parameters are documented in the schema. The description adds the crucial meaning of confirm (dry run without it) but doesn't elaborate on other parameters like cwd, async, profile, or timeout. Baseline 3 is appropriate as the schema covers the basics.

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 it deletes an environment with all its contents, and the verb 'delete' is specific and unambiguous. It distinguishes from sibling tools like cs_admin_reset_environment by emphasizing irreversibility and full deletion.

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 clearly states that it mutates a live environment and requires confirm: true, implying this is for when deletion is intended. It does not explicitly list alternatives or when not to use it, but the irreversibility warning and the contrast with reset tools gives clear context. Sibling tools like reset or backup are not named, but the destructive nature is emphasized.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool runs 'pac admin status' and uses the active pac auth profile, which is useful, but it does not state whether the operation is read-only, what the returned status format looks like, or any auth/precondition requirements.

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 two short sentences with no filler. The purpose is front-loaded, and the underlying command is identified concisely in the second sentence.

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 simple status-query tool with all-optional parameters, the description provides the essential purpose and underlying command. However, without an output schema or annotations, it does not describe the return value or clarify how this tool relates to polling/status siblings, leaving moderate ambiguity.

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 describes all four parameters, with 100% coverage, so the description is not required to explain them in depth. The description's mention of the active pac auth profile adds minimal information beyond the schema's existing 'profile' parameter description.

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 clear resource ('tenant operations that are still running') and specifies the kind of information provided ('status'), with concrete examples such as copies, restores, resets, and deletions. It distinguishes itself reasonably from generic status tools through the tenant-operation scope, though it does not explicitly contrast with sibling tools like cs_job_status or cs_status.

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

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

There is no explicit guidance on when to choose this tool over cs_job_status, cs_status, or other admin inspection tools. The description implicitly suggests it is for checking in-progress tenant operations, but it does not state exclusions or alternatives.

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?

No annotations are provided, so the description carries the burden. It discloses that the tool runs a specific pac command and uses the active auth profile, which implies a read-only listing behavior. However, it doesn't disclose output format, pagination, or whether it requires admin elevation beyond the profile mention.

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

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

Two sentences, front-loaded with the core purpose and the underlying command. The second sentence adds the execution mechanism. 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 simple read-only list command with 100% schema coverage, the description is mostly adequate. However, with no output schema and no annotations, it could usefully mention what the output contains (e.g., application IDs, names) and whether any prerequisites like being signed in are required.

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 schema already documents all four parameters. The description adds context that the profile is the admin account for tenant commands and that cwd is for project commands, but this is largely restating schema info. 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 lists Entra applications registered with the tenant for Power Platform, and identifies the underlying command ('pac admin application list'). It is distinguishable from siblings like cs_admin_list_service_principals and cs_admin_register_application, though it doesn't explicitly name them.

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 implies usage context: it's a read-only admin listing command for tenant-registered Entra applications. It mentions it runs with the active pac auth profile, but doesn't explicitly state when to prefer this over alternatives like cs_admin_list_service_principals or cs_admin_list_app_templates, nor does it state exclusions.

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?

There are no annotations, so the description carries the behavioral burden. It discloses that it runs 'pac admin list-app-templates' with the active pac auth profile, which is useful, but it does not explicitly state read-only behavior, output shape, or any side-effect-free guarantee beyond what 'list' implies.

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

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

Two sentences, front-loaded with the core purpose and scoped by region, followed by the underlying command. There is 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?

The description covers purpose, scope, and command, and the schema covers all parameters. However, with no annotations and no output schema, it does not describe the return format or explicitly confirm there are no side effects, leaving a moderate gap for an agent deciding how to use the result.

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 parameters are already fully documented. The description adds no parameter-specific meaning beyond 'per region' and the active auth profile, both of which are also reflected in 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 clearly states the tool lists Dynamics 365 application templates available per region, with a concrete underlying command. It names a distinct resource not covered by any sibling admin list tool, so an agent can differentiate it from cs_admin_list_environments, cs_admin_list_applications, etc.

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 context: these are templates used when creating an environment, and results are region-specific. It does not explicitly name alternative tools or state when not to use it, but the usage context is 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?

With no annotations, the description carries the full behavioral burden. It does disclose the underlying command and that it uses the active pac auth profile, which is useful. However, it does not explicitly state that this is a read-only operation, nor does it mention any side effects, output shape beyond labels/dates, or failure behavior. The command name implies listing only, but an explicit safety statement would strengthen it.

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

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

Two sentences with no filler. The core purpose, the restore relationship, and the underlying command are all front-loaded. Every clause earns its place.

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

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

For a simple list operation, the description is largely complete: it names the returned data (labels and dates), the command, and the restore context. Although there is no output schema, the description compensates by naming the key output fields. It could mention that no parameters are required and that the operation is read-only, but the schema covers required parameters and the command name makes the read-only nature reasonably clear.

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

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

Schema description coverage is 100%, so each parameter already has a meaningful description and no defaults are undocumented. The tool description adds only contextual framing (environment backups, active profile) rather than new parameter-level detail, which is acceptable at the baseline for full 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 clearly identifies the resource (environment backups) and the data returned (labels and dates), and explicitly ties it to 'pac admin list-backups'. It also distinguishes itself from the related restore tool by stating these are exactly 'what cs_admin_restore_environment can restore'. This is a specific, unambiguous purpose with sibling differentiation.

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 context: this tool lists restorable backups for an environment loose, and names cs_admin_restore_environment as the companion tool. It does not explicitly state when not to use it or alternative listing tools, but the intended use-case is clear enough for an agent to select it over backup/restore siblings.

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?

With no annotations, the description carries the full burden. It transparently states the underlying command ('pac admin dlp-policy list') and the auth profile dependency. It does not mention output format, pagination, or permission requirements, though the list command implies a read-only operation.

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 two sentences with no wasted words. The definition of DLP policies is front-loaded and helpful, followed by the exact command and auth context. 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?

The tool is a simple list operation with all parameters self-documented in the schema. The description provides essential context about what DLP policies are and the command executed. It does not describe the return shape, but the tool name and command strongly imply a list of policies, and no output schema exists to set a higher bar.

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 schema already documents all four parameters. The description adds no parameter-specific meaning beyond that, so the baseline 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 clearly states the verb (list) and resource (DLP policies) and adds useful context about what DLP policies are (connector groups that decide which connectors an agent or flow may combine). It does not explicitly differentiate from the sibling cs_admin_show_dlp_policy, but the command and scope ('in the tenant') make the purpose clear.

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 implies usage: listing all tenant-level DLP policies via a specific pac command. It provides context about the tenant scope and active auth profile, but it gives no explicit guidance on when to prefer this over alternatives like cs_admin_show_dlp_policy or when not to use it.

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?

No annotations are provided, so the description carries the full burden. It discloses that it runs 'pac admin list-groups' with the active pac auth profile, which is useful but doesn't reveal whether the operation is read-only, what the response format is, or any side effects. For a listing command, it likely returns data without mutations, but this is not stated. This is a significant gap given zero annotation 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 two sentences with no filler. It leads with the core purpose, then adds the underlying command and auth detail. Every word earns its place. It's optimally concise for a straightforward listing 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?

For a simple listing tool, the description covers what it lists and how it runs, but it omits behavioral specifics like output format, pagination, or read-only nature. Since there is no output schema and no annotations, an agent might not know what to expect from the call. It's not a complex tool, so it's minimally complete but lacks the transparency that would make it fully self-contained.

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% description coverage, so all four parameters (cwd, profile, background, timeoutSeconds) are already documented. The tool description adds no extra parameter information. Baseline of 3 is appropriate because the schema does the heavy lifting, and the description doesn't introduce any ambiguity.

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 it lists environment groups in the tenant and specifically ties them to managed-environment rules. It distinguishes from sibling tools like cs_admin_list_environments by focusing on groups, not environments. It also names the underlying command, making the action concrete. However, it does not explicitly contrast with any sibling, so it loses a point.

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 implies usage for managed-environment rules, which suggests when to call it. But it provides no explicit guidance on alternatives, exclusions, or when not to use it. For example, it doesn't say to use cs_admin_list_environments for a plain environment list. This is implied rather than stated, so it's adequate but not strong.

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?

With no annotations, the description carries the behavioral burden. It discloses the underlying command ('pac admin list'), the dependency on the active pac auth profile, and the read-only listing nature. It does not discuss failure modes or auth prerequisites, but it provides meaningful 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 two sentences with no filler. It front-loads scope and output fields, then mentions filters and the underlying command, with every clause contributing useful information.

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

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

For a read-only list command with a fully documented schema, the description covers the essential semantics and names return fields. It lacks explicit routing guidance against cs_list_environments and does not describe output format details, but it is otherwise complete enough for an agent to 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?

Schema description coverage is 100%, so the baseline is 3. The description summarizes filters and the underlying command, but does not add meaning beyond what the schema already documents for each parameter.

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 action (list), resource (environments), scope (every environment in the tenant), and the output fields (type, region, state). It also distinguishes the tool from the non-admin sibling cs_list_environments by explicitly saying 'as the admin centre lists them'.

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 context: this is for tenant-wide admin listing, using the active pac auth profile. It does not explicitly name alternatives or exclusion criteria, but the admin-centre framing makes the intended use case clear.

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?

With no annotations, the description carries the burden. It discloses the underlying command ('pac admin list-roles') and that it uses the active pac auth profile, and clarifies child roles are optional. It doesn't explicitly state the operation is read-only or note any permission requirements, though 'list' strongly implies it.

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

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

Two tight sentences front-load the purpose and scoping, then add the command and auth-profile context. No filler or repetition.

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

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

For a read-oriented list command, the description plus fully documented schema covers invocation: environment, optional child roles, profile, and background execution are all present. It doesn't describe return shape, but the output of a list-roles command is reasonably predictable.

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 schema already documents all seven parameters. The description adds only the contextual link to assignment tools and the optional-child-roles behavior, which is useful but not parameter-level detail.

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-resource pair ('list security roles in an environment') and adds the key semantic that these roles are exactly what cs_admin_assign_user and cs_admin_assign_group can grant. This distinguishes it from other admin list 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?

It gives clear context: use when you need to enumerate the roles available to grant in an environment, optionally including child roles. It doesn't explicitly list alternatives or exclusions, but the assignment-tool tie-in routes the agent correctly.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It usefully states that it runs 'pac admin list-service-principal' and uses the active pac auth profile, covering the auth dependency. However, it does not explicitly state that it is read-only or describe any side-effect absence or output behavior.

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

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

The description is two short sentences. It front-loads the core purpose and immediately gives the exact execution command, with no filler or redundant 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 fully documented parameter schema and the simplicity of a list operation, the description provides enough context to select and invoke the tool. It would be stronger with explicit output-shape or side-effect disclosure, but nothing essential for calling the tool 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%, so the baseline is 3. The description adds a bit of command context by naming the exact pac command, but it does not enrich the semantics of max, filter, cwd, or timeout 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 definition clearly identifies the action ('List') and the specific resource: service principals with Dataverse access, described as Entra applications with an application user in Dataverse. It names the underlying command, making it distinct from sibling list tools like cs_admin_list_applications.

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 clear context for when this tool is appropriate: finding application identities that can act without a person signing in. It does not explicitly name alternatives or provide when-not conditions, but the purpose is specific enough to guide 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?

With no annotations, the description must carry the transparency burden. It discloses that with settingsFile it writes JSON to a path and that the file is the reference copy, and that it runs under the active auth profile. However, it does not explicitly state that this is a read-only operation (though implied by 'list'), nor does it describe the default output when settingsFile is not provided, or any permission or side-effect details. This is partial but not comprehensive.

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 two sentences and front-loads the primary purpose before adding the settingsFile detail. It is efficient with no redundancy, though it could be slightly more structured to separate core behavior from the file-writing nuance. Overall, it earns its sentences.

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 read-only list tool with no output schema, the description covers the main operation and the settingsFile behavior, but it leaves ambiguity about what happens when settingsFile is omitted (presumably console output, but not stated). It also does not mention authentication prerequisites beyond the active profile, or any limitations. Given the simplicity, it is adequate but not fully complete.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds value by explaining the purpose of settingsFile as a reference copy for source control, which is not in the schema. However, it does not elaborate on the other parameters (cwd, profile, background, timeoutSeconds) beyond what the schema states, so it provides minimal additional semantic context overall.

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 reading tenant-wide Power Platform settings (governance, sharing, support, licensing) and references the underlying 'pac admin list-tenant-settings' command. It distinguishes the read intent from the update sibling (cs_admin_update_tenant_settings) by title, but does not explicitly name the alternative, so it falls short of a 5.

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

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

The description implies usage for reading tenant settings but provides no explicit guidance on when to choose this over alternatives or when not to use it. It does not mention exclusions or conditions. The mention of settingsFile being a reference copy suggests a source-control use case, but this is not framed as a decision rule.

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?

With no annotations, the description is the only source of behavioral disclosure. It does say the tool runs a tenant query, wraps `pac admin query`, uses the active profile, and can write to a file—useful side-effect context. However, it does not explicitly say the operation is read-only, what happens if an output file already exists, or what the tool returns when no file is requested.

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 only two sentences and front-loads the core purpose before the optional file-writing behavior. It earns its place and does not spend words on generic detail, though the 'JSON, list or CSV' phrase is a small factual mismatch with the schema enum.

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 has 8 parameters and no output schema, so the schema carries most of the invocation details that the description does not. The description is broadly informative but does not illuminate the actual query-language syntax, provide examples, or explain the return convention for normal vs. background execution.

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 each parameter already has meaningful documentation, so the description is not required to add much. The file-format mention is mildly useful but is also somewhat inconsistent with the `outputType` enum, which only lists `Json`, `List`, and `Grid`; `CSV` is not a valid enum value.

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

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

The description states a specific verb and resource—'Run a tenant-level resource query (the admin centre's own query language)'—and names the underlying command `pac admin query`, distinguishing this from the many sibling cs_admin_* tools. It adds useful detail about optional file output and the active auth profile.

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

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

There is no guidance about when to use this tool versus alternatives like `cs_admin_list_environments`, `cs_admin_environment_status`, or the generic `cs_pac` wrapper. The description explains what the tool does, but not when it should be chosen, when it should be avoided, or what the admin-centre query language is for.

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?

With no annotations provided, the description carries the full behavioral disclosure burden. It clearly states that the tool mutates a live environment, requires confirm: true, performs a dry run otherwise, and runs through the active pac auth profile. This is solid behavioral context, though it slightly repeats the confirm requirement.

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

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

Three sentences, front-loaded with the core purpose, and no filler. The only minor weakness is repeating 'requires confirm: true' in two consecutive sentences, which is slightly redundant but not harmful.

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 mutating admin tool with no annotations and no output schema, the description covers the essential operational facts: what it does, that it mutates, how to actually apply the change (confirm: true), and that a dry run happens otherwise. Combined with fully documented parameters, an agent has what it needs to 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?

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds context about the confirm flag's dry-run behavior and the active profile, but it does not materially expand on parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Register an Entra application with the tenant so it can be used by Power Platform.' This is distinct from the sibling cs_admin_unregister_application and clearly names the underlying command 'pac admin application register'.

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 makes the use case clear — registering an Entra application for Power Platform — and notes the important confirm flag requirement. It does not explicitly name alternatives or when not to use it, but the register/unregister sibling pair and the title make the primary usage obvious.

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?

With no annotations, the description carries the behavioral burden. It clearly discloses that the operation mutates a live environment, deletes everything, requires confirmation, and will dry-run otherwise. It does not detail auth requirements or output, but the core destructive behavior is explicit.

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

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

Three short sentences and front-loaded purpose. Minor redundancy: confirm: true and dry-run behavior are stated twice, so it is concise but not maximally tight.

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 destructive admin operation with no output schema and no annotations, it covers the essential call contract: destructive effect, confirmation gate, dry-run behavior, and underlying pac command. It leaves return-value expectations implicit, but schema covers the remaining parameters.

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 schema already documents all 15 parameters. The description adds only confirm/profile context already reflected in the schema, meriting the baseline 3.

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

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

The description states a specific verb and resource ('Reset an environment to an empty Dataverse instance') and clarifies scope by warning that everything in it is deleted, distinguishing a reset from environment deletion/backup/restore siblings.

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

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

It gives clear usage context: this is for resetting a live environment, requires confirm: true to avoid a dry run, and operates under the active pac auth profile. It does not explicitly name alternatives or when-not conditions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool mutates a live environment, overwrites data and customisations, requires confirm: true to execute (otherwise a dry run), and runs a specific command. This is substantial behavioral context for a mutation tool.

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

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

The description is three sentences and front-loaded with the core purpose. However, it repeats the confirm requirement twice (first and third sentences), which is redundant and slightly inefficient. Overall it is concise but not perfectly streamlined.

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 12-parameter mutation tool with no output schema and no annotations, the description covers the essential behaviors: it mutates, overwrites, requires confirm, and is a dry run otherwise. It does not explain the return format or error scenarios, but these are not typically required for such a tool. The description is adequate for an agent to call 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?

The schema covers 100% of parameters with descriptions, so the description adds little beyond the schema. It repeats the confirm requirement but does not clarify parameter relationships (e.g., sourceEnvironment vs targetEnvironment) or format nuances 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 verb 'Restore', the resource 'a backup into the same or another environment', and the critical effect 'Overwrites the target's data and customisations'. It also names the underlying command 'pac admin restore'. This distinguishes it from siblings like cs_admin_backup_environment and cs_admin_copy_environment.

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 implies the usage context (restoring from a backup) and notes the confirm requirement for actual mutation, but it does not explicitly state when to use this tool vs alternatives or provide exclusion criteria. No comparison to other admin tools is given.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool mutates a live environment, requires confirm:true to actually change anything, and otherwise performs a dry run. It also reveals the underlying command and profile usage. This is strong transparency for a mutation tool, although it repeats the confirm requirement twice and doesn't mention side effects (e.g., reversibility).

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 brief but contains redundancy: it repeats 'requires confirm: true' verbatim in the third and fifth sentences, and 'Changes a live environment' vs 'Mutates a live environment' say the same thing. The information is front-loaded with the purpose, but the repetition wastes words. It could be tightened without losing clarity.

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 the critical behavioral aspects: the admin prerequisite, the confirm requirement (and dry-run alternative), and the underlying command/profile. It does not explain return values (no output schema), but for a mutation tool that's likely acceptable. The environment parameter is only in the schema, not the description, but given 100% schema coverage, that's not a gap. Overall, the context is sufficiently complete for an agent to call 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 covers all 6 parameters with descriptions (100% coverage), so the description adds little beyond what the schema already provides. The mention of 'confirm: true' and 'active pac auth profile' reinforces schema entries but doesn't add new meaning. Given high schema coverage, a 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 states the exact action: 'Give yourself the System Administrator role in an environment.' This is a specific verb and resource, clearly distinguishing it from any sibling tool (no other tool appears to perform self-elevation). The purpose is unambiguous and self-contained.

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 lists the required admin roles ('Needs Global, Power Platform or Dynamics 365 admin') and the critical confirm flag requirement for mutating a live environment. It also indicates the underlying mechanism (running 'pac admin self-elevate'). While it doesn't name an alternative tool, none exists among siblings, so this is acceptable. The guidance is clear about prerequisites and the confirm behavior.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool mutates a live environment, requires confirmation, defaults to a dry run, and runs a specific pac command with the active profile. This is strong disclosure for a mutating operation.

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 short but redundant: 'Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true' repeat the same fact. The command invocation detail is useful, but the duplication weakens the structure.

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 mutating tool with 9 parameters and no output schema, the description covers the essential invocation behavior: live-environment mutation, confirm semantics, dry-run behavior, and the underlying command/profile. The schema covers parameter formats, and no critical operational detail needed for a correct call 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%, so the baseline is 3. The description adds meaning beyond the schema by spelling out the allowed day values and by explaining that confirm is required to actually apply changes rather than perform a dry run.

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 action ('Set how many days backups of an environment are kept') and a resource with valid values. This clearly distinguishes it from sibling backup operations like creating, listing, or restoring backups.

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 clear usage context: changes to a live environment require confirm: true, and without it the tool performs a dry run. It doesn't explicitly name alternatives or exclusion cases, but the operational prerequisite is clear enough for an agent to know when to invoke it and how.

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?

No annotations exist, so the description carries the full burden. It explicitly discloses that the command requires 'confirm: true' to avoid a dry run, mutates a live environment, and runs a specific pac command under the active auth profile. This is strong behavioral transparency for a mutating operation.

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 front-loads the main purpose and is generally tight. The phrase 'requires confirm: true' appears twice, which is redundant and adds noise. With that trimmed it would be near-ideal.

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 has 19 parameters and no output schema, so the description needs to clarify the command's effect and preconditions. It covers the key behavioral aspects (confirm, dry run, mutation, profile) but doesn't mention return value or how it surfaces the pac command output. That's a minor gap, not critical.

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

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

Input schema covers 100% of parameters, so baseline is 3. The description mentions sharing limits, solution checker mode, and maker onboarding, but these are already obvious from parameter descriptions. It adds no additional meaning about parameter formats, defaults, or relationships 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 clearly states a specific action (turn managed environments on/off) and the governance options it configures (sharing limits, solution checker mode, maker onboarding). It distinguishes this from sibling admin tools by focusing specifically on managed environments governance, and the 'Standard'/'Basic' mapping to protectionLevel reinforces 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 provides context that this changes tenant governance and mutates a live environment, which tells an agent when to reach for it. However, it doesn't explicitly state when not to use it or name alternative tools (e.g., cs_admin_update_tenant_settings). No exclusions or comparisons are given.

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 explicitly states that it mutates a live environment and requires 'confirm: true' (a dry run otherwise), which is critical behavioral information. Since no annotations are provided, the description carries the full burden, and it adequately discloses the mutating nature and the confirm requirement. It also mentions it runs a specific command, providing transparency about the underlying operation.

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 reasonably concise, using two sentences to convey the core purpose and the critical confirm requirement. The key behavioral note about mutation is front-loaded in the first sentencecars. However, there's slight redundancy when it says 'Changes a live environment: requires confirm: true' and then repeats 'Mutates a live environment: requires confirm: true'. This repetition wastes a bit of space.

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 (10 parameters, 2 required) and the rich schema descriptions, the description provides the essential behavioral context (mutation and confirm requirement). However, it doesn't elaborate on return values or error scenarios, and with no output schema, the agent might not know what to expect. The description also doesn't fully explain the 'backgroundOperations' parameter's semantics, relying on the schema.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description doesn't add much beyond what the schema already provides for parameters like 'runtimeState' and 'backgroundOperations', but it does emphasize the 'confirm' parameter's significance. The description doesn't explain the relationship between 'async', 'background', and 'maxAsyncWaitTime' in more detail than 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 clearly states the tool's purpose: to put an environment into administration mode or back, and to control background operations. It mentions the underlying command ('pac admin set-runtime-state'), which helps distinguish it from other admin tools. However, it doesn't explicitly name a sibling tool for comparison, so it's clear but not fully differentiated.

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

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

The description explains that it changes a live environment and requires 'confirm: true' to avoid a dry run, which gives important usage context. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like cs_admin_environment_status or cs_set_flow_state. The mention of the 'active pac auth profile' implies usage context but doesn't explicitly state exclusions.

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?

There are no annotations, so the description must carry the behavioral transparency burden. It does add useful context by stating the exact pac command ('pac admin dlp-policy show') and that it uses the active auth profile, and 'show' implies a read-only operation. However, it does not explicitly state that no changes are made, nor does it describe output format, error conditions, or authorization needs.

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 two concise sentences that front-load the tool's purpose and then provide the key execution detail (the pac command and auth profile). Every phrase adds value, and there is no redundant repetition of the title or schema.

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 straightforward show operation with fully documented parameters sideways, the description covers the core output content ('connector classification and the environments it applies to') and the execution mechanism. No output schema exists, but the description gives enough insight into what the result contains. It is slightly incomplete in not stating any output format or edge cases, but it is largely sufficient for the tool's simplicity.

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%, with all five parameters already documented in the input schemaSer the description adds no additional parameter-level meaning beyond 'policy in full' and the underlying command. The baseline of 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 states a specific verb ('show'), resource ('data loss prevention policy'), and scope ('One ... in full'), and hints at the distinguishing factor from the sibling list tool by emphasizing the full policy details. However, it does not explicitly contrast it with cs_admin_list_dlp_policies, so it falls just short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as cs_admin_list_dlp_policies for browsing policies or other admin tools. It mentions the underlying command and active auth profile, but offers no context for selecting this tool or what prerequisites are needed beyond a policy name.

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