Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Copilot Studio MCP clone the marketing agent from the live environment into my workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets a coding agent (GitHub Copilot in VS Code, Claude Code, or any other MCP client) build, test, ship and look after Microsoft Copilot Studio agents from the editor.
An agent becomes a folder of YAML you can read, diff and commit. The server writes that folder the
way the Copilot Studio VS Code extension does, syncs it with the live agent through the official
Power Platform CLI (pac), and calls the Power Platform, Dataverse, BAP, Power Automate and
DirectLine APIs for what the CLI does not cover: evaluations, chat, cloud flows, portal drift,
transcripts. Nothing reaches a live environment without your approval, and when a choice is still
open the tool asks a question instead of failing.
You want to | What happens | Read |
Stand up a new agent and get it live | create it inside a solution, generate instructions, add knowledge, topics and tools, review, validate, push, publish, talk to it | |
Change an agent that already exists | clone it to files, edit or remove components, review, merge what colleagues changed, push | |
Give the agent something to call | connector actions, MCP servers, cloud flows, AI Builder prompts, other agents, chosen from what the environment actually has | |
Know whether it works | chat with the published agent, repeatable conversation tests, evaluation runs with per-case results | |
Learn from real users | transcripts, session outcomes, escalation rate, a regression test set built from real questions | |
Not overwrite what a colleague did in the portal | see portal changes since your last sync, block a push that would collide, merge | |
Write a Power Automate flow without hand-writing Logic Apps JSON | compose a definition from steps, create the flow, bind its connections, switch it on, read its run history | |
Find out why a flow keeps failing | resolve the real error behind a failed connector action, diff the run against one that worked, and see where the failures concentrate | |
Move to test and production | pull the whole solution, map connections and variables, deploy 1:1, publish; or use a pipeline | |
Prove the stages match | snapshot each environment, compare, gate a pipeline on drift | |
Run the tenant | environments, security roles, DLP, tenant settings, backups to files, onboarding a team, the Microsoft 365 agent catalogue |
The complete tool list is in docs/tools.md and the diagrams in
docs/flows.md; both ship
inside the npm package under docs/. The reference sections at the end of this page cover the
agent settings the server can write,
authentication and permissions,
configuration, the hard limits and
how this differs from pac's own MCP server.
Related MCP server: copilot-studio-code
Early release. What has actually been exercised:
Offline: 251 unit tests over the compiled output, plus a pack oracle that round-trips every
authoring tool's YAML through pac copilot init and pac copilot pack.
Against a real tenant (2026-09-08, phases A to F of docs/live-verification.md): the
connector registry, the pac connection list layout, pac copilot clone and its sync metadata,
drift detection and the cs_push conflict refusal, and the evaluation path end to end including
the portal's CSV import format and the metric status strings. A portal-made agent validates
clean, so cs_validate produces no false positives on real content. That run also caught a real
bug: pac copilot publish prints "Failed to publish" and exits 0, so a failed publish was being
reported as a success. Fixed.
Not yet verified live: the transcript tools, cs_check_drift in quick mode, cs_chat, the
Dataverse listBots path, moving a solution between environments, and every flow the flow
builder produces (none has been imported into an environment yet).
docs/verify.md is the short list of what is still open, docs/STATUS.md the full record. Read
the dry run before confirming anything that writes.
Node.js 20+.
.NET 10 SDK and the Power Platform CLI: dotnet tool install --global Microsoft.PowerApps.CLI.Tool.
If the SDK lives in your user profile, set DOTNET_ROOT to that folder; the server defaults it
to ~/.dotnet when that folder exists.
A pac auth profile for the environment you work in, created once in a terminal:
pac auth create --environment <id or URL>. Everything that goes through pac (create, clone,
pull, push, publish, solutions, administration) uses it, with Microsoft's own first-party app.
For the API-based tools (environments, evaluations, chat, flows, drift, transcripts): an Entra
sign-in through cs_login, done from the session. By default no app registration is needed;
Authentication and app registration says when you need
one and which permissions it must carry.
The server is on npm as copilot-studio-mcp, so the usual install is no install: point your MCP
client at npx, and the first start fetches the package.
There is also a VS Code extension, vscode-extension/, which registers the server with VS Code's
MCP host and exposes the environment variables below as settings. It carries the server and its
dependencies inside the VSIX, so it needs no npm and no network on first start. Build it with
cd vscode-extension && npm install && npm run package; install the resulting .vsix with
code --install-extension copilot-studio-mcp-<version>.vsix.
VS Code, from a terminal or by hand in .vscode/mcp.json (workspace) or the user-level mcp.json:
code --add-mcp '{"name":"copilot-studio","command":"npx","args":["-y","copilot-studio-mcp"]}'{
"servers": {
"copilot-studio": {
"type": "stdio",
"command": "npx",
"args": ["-y", "copilot-studio-mcp"],
"env": { "CPS_WORKSPACE": "${workspaceFolder}" }
}
}
}Claude Code (user scope):
claude mcp add-json copilot-studio '{"type":"stdio","command":"npx","args":["-y","copilot-studio-mcp"]}' --scope userMistral Vibe, in ~/.vibe/config.toml (or $VIBE_HOME/config.toml; a ./.vibe/config.toml in
the working folder takes precedence). Vibe gives a server 10 seconds to start by default, which a
first npx fetch on a corporate network can exceed, so install globally and run the entry point
with node (find the folder with npm root -g). On Windows, keep paths in single quotes: TOML
reads backslashes inside double quotes as escapes, and "C:\Users\..." is not valid TOML.
[[mcp_servers]]
name = "copilot-studio"
transport = "stdio"
command = "node"
args = ['C:\Users\<you>\AppData\Roaming\npm\node_modules\copilot-studio-mcp\dist\index.js']
startup_timeout_sec = 60 # default 10
tool_timeout_sec = 300 # default 60; solution exports and evaluation runs take longernpm install -g copilot-studio-mcp with "command": "copilot-studio-mcp" avoids the npx start-up
cost. The server is published to the MCP Registry as io.github.jgt87/copilot-studio-mcp, which is
what VS Code's MCP gallery (Extensions view, search @mcp) draws from through the GitHub MCP
Registry. To run from a clone instead, see Development.
Environment variables are optional and listed under Configuration.
cs_init. Reports pac and .NET, the pac profiles and which one is active, the MSAL sign-in,
the write policy in force, the workspace it found and the next steps for it. It also returns a
menu of tool presets; on a smaller model pick one (see
Running on a smaller model).
cs_login when a cloud tool needs it. The call opens the browser from the server and returns
within 15 seconds; if the sign-in has not finished by then it returns status: pending with the
URL so you can open it yourself, and the next cloud call (or cs_login_status) picks the token
up. That is what makes sign-in work from clients that cap tool-call duration or run the server
where no browser can be launched. Device code (mode: device_code) is the alternative where the
tenant allows it; many block it by Conditional Access policy.
cs_guide <topic> when you want the walkthrough for one job rather than inventing a
sequence: getting-started, instructions, knowledge, tools, topics, evaluations,
publish-and-test, drift, transcripts, solutions, administration, troubleshooting.
Each names the tool per step, the portal steps that cannot be automated, and the next steps for
your workspace. Six MCP prompts (new agent, add knowledge, add tool, write instructions, review
and push, check drift) wrap the same walkthroughs in clients that show prompts as commands.
The server never changes a live Copilot Studio environment on its own. Every tool that can
(cs_push, cs_publish, cs_run_evaluation, cs_import_solution, cs_deploy_solution,
cs_create_agent with an environment, the delete tools, the flow and admin tools that write, and
the environment-changing pac wrappers) returns a dry run describing what it would do, and does
nothing else, until it is called again with confirm: true. The calling agent is instructed, in the
MCP handshake, to show that dry run and pass confirm only after you agree; one approval covers one
call.
Changing the agent on disk asks the same way, for the same reason: an edit you did not intend is
cheap to make and expensive to notice. cs_add_topic, cs_add_knowledge_source, cs_add_tool,
cs_add_flow, cs_add_trigger, cs_add_variable, cs_edit_topic, cs_edit_tool,
cs_edit_knowledge, cs_update_settings, cs_update_agent and cs_generate_instructions write
nothing on the first call. They return the change instead - a file that would be created shown in
full, a file that would be edited shown as a diff against what is there now - and write it when the
same call is repeated with confirm: true. Reviewing, validating and describing read only, and ask
nothing.
The prose fields get their own accounting, because they are the change a diff alone does not
settle: the preview carries the character count and how much of the product's limit is left, and an
edit that would exceed it is refused outright rather than failing at push time. The limits are not
the same - instructions holds 8000 characters, and the Settings > Responses > "Response
formatting" box (responseInstructions) only 500.
For a hard lock, set CPS_READ_ONLY=1 in the server's environment: the environment-changing tools
are then not registered at all, so no confirmation can reach the environment, while authoring,
validation, review and the read-only tools keep working. cs_init reports the mode and which tools
are withheld. test/policy.test.js fails if a tool that declares confirm is missing from that
list, so the two layers cannot drift apart.
Three more behaviours you will meet in every workflow:
A question instead of an error. When a call cannot proceed because something has not been
decided (which connector, which operation, which agent), the tool returns needsInput: true with
what it needs, why, the real choices when the server can list them, and the tool that lists more.
Nothing is written; the calling agent asks you and calls again. This works in every client,
including those without MCP elicitation.
Long calls run in the background. MCP clients cap a tool call at about a minute. Tools that
can run longer (cs_pull_solution, cs_create_auth_profile, environment provisioning, every pac
wrapper) accept background: true, return a jobId at once, and cs_job_status reports the
phases and the result from an on-disk record that survives a server restart. A tool decides
whether it may change anything before it starts a job, so the confirm contract is unaffected.
Writes are never retried. A read that fails on a transport error or a 429/5xx is retried with
backoff and honours Retry-After; a publish or an import that timed out may already have been
applied, so it is reported, not repeated.
Making agents and administering the tenant are usually different accounts. pac keeps one active authentication profile per machine, so create one profile per account and let the server switch:
pac auth create --name maker --environment <environment id or url>
pac auth create --name admin --environment <environment id or url>Or from the session: cs_create_auth_profile with name, environment and background: true,
because pac opens its own browser and waits for the sign-in (cs_job_status reports when the
profile exists). cs_list_auth_profiles shows the profiles and which is active.
Core sync and solution tools use CPS_PAC_PROFILE; admin commands and tenant backup use
CPS_ADMIN_PROFILE; every pac wrapper and cs_pac also accept an explicit profile. When the
server selects a profile it restores the previous one afterwards, and every pac call in the process
shares one queue, so multi-step operations (bootstrap, solution pull and deploy, snapshots) hold
the profile for the whole run. Other server instances and terminal pac commands are outside that
coordination. The MSAL sign-in used by the API-based tools is separate again and independent of pac.
From an empty folder to a published agent you can talk to. Each step is one tool call; the steps that change the environment show a dry run first.
Pick the environment. cs_list_environments (needs cs_login), or take the environment id
from the Copilot Studio URL.
Pick or create the solution. cs_list_solutions shows what exists; an existing solution
works as long as it is unmanaged and you use its publisher prefix. To start a solution for your
agents: cs_create_solution uniqueName=contoso_Agents publisherPrefix=contoso confirm=true.
The solution is the unit you later export and import to move the agent to test and production,
so it is worth choosing rather than letting one be created per agent.
Create the agent inside it.
cs_create_agent name="Contoso Support" publisherPrefix=contoso projectDir=./contoso-support environment=<id> solutionName=contoso_Agents confirm=true (add createSolution=true to fold
step 2 in). The server scaffolds locally with pac copilot init, packs with the solution name,
imports, then clones the live agent back so projectDir is a sync-connected workspace with the
default system topics. Without environment you get a local scaffold only, which can pack
settings, agent and topics but not knowledge, tools or flows.
Leave out publisherPrefix or projectDir and the tool asks instead of guessing, listing the
publishers in the environment (and, when you named a solution, the one prefix that solution's
publisher allows) and suggesting a folder named after the agent. The prefix is worth the
question: it becomes part of the schema name of every component the agent will ever have
(contoso_contososupport.topic.Greeting), it cannot be changed afterwards without recreating
them, and it has to match the publisher of the solution the agent lands in.
Say what the agent is for. cs_generate_instructions purpose="Answer IT questions and create ServiceNow tickets" audience="Employees" tone="Friendly, brief" boundaries=["never reset passwords"] modelName="Agent instructions" drafts the instructions with an AI Builder prompt
(cs_list_prompts shows the prompts in the environment; create a "write agent instructions"
prompt once in AI Builder if you have none). Review the draft, call again with apply=true to
write it into agent.mcs.yml; later refine=true with a changeRequest revises what is
there. Or write them yourself with cs_update_agent, which also sets response instructions and
mode, conversation history, capabilities, moderation, model and conversation starters (the
full map).
Give it something to work with. cs_add_knowledge_source for a public website, SharePoint,
a Graph connector or uploaded files; cs_add_topic for deterministic conversations built from
trigger phrases plus message, question, condition, set-variable, redirect, HTTP, flow, generative
answers (optionally scoped to named knowledge sources), adaptive card, transfer and end nodes;
cs_add_tool for anything the agent should call (the tools workflow).
cs_add_trigger and cs_add_variable cover event triggers and global variables.
Review and validate. cs_review_agent is a rules-based read of the whole workspace with a
10-point score: missing escalation or fallback, weak tool descriptions, overlapping trigger
phrases, private knowledge with no authentication, secrets in files. Each finding names the rule
and the fix. cs_validate then checks every file against the authoring schema (744 definitions)
and across files: connection references that nothing binds, catalog operations that do not
exist, redirects to topics that are not there. It also blocks on the mistakes that a push
accepts without complaint and then stores wrongly: merge-conflict markers left by a pull (the
push keeps only the text before them), leftover <AGENT_SCHEMA> placeholders, file and schema
names pac rejects, and more than 200 trigger phrases. It warns about text cut off by an
unquoted #, nodes after an end node, formulas missing their =, adaptive cards without a
submit action, and topic names with a period, which stop the solution from exporting.
Push. cs_push confirm=true is the portal's Save: the draft agent now shows your topics,
knowledge and tools. The dry run runs validation and the quick drift check first, and the push
is refused when a colleague changed the same component in the portal since your last pull.
Tools with a connection reference need one portal step: open the tool under the agent's Tools,
Connect, then cs_pull to bring the binding down.
Publish and talk to it. cs_publish confirm=true, then cs_chat utterance="my laptop is slow". The testing workflow turns that into repeatable checks.
flowchart TD
A["cs_init"] --> B["cs_list_solutions<br/>pick one, or cs_create_solution"]
B --> C["cs_create_agent<br/>environment + solutionName + confirm"]
C --> D["cs_generate_instructions<br/>AI Builder prompt, then apply"]
D --> E["cs_add_topic / cs_add_knowledge_source / cs_add_tool<br/>(cs_list_connectors, cs_describe_connector)"]
E --> R["cs_review_agent"]
R --> H["cs_validate"]
H -- errors --> E
H -- clean --> I["cs_push confirm"]
I --> J{"tool needs a connection?"}
J -- yes --> J1["portal: authorise once"] --> J2["cs_pull"] --> K
J -- no --> K["cs_publish confirm"]
K --> L["cs_chat"]GitHub Copilot harness agents (cs_create_agent with authoringMode: cli-copilot) are a smaller
surface: init, pack, import, instructions and chat. Topics and evaluations are standard-harness
features.
Most agents already exist, often made in the portal. The loop is clone, change, review, merge, push.
Clone it. cs_list_agents (through pac or Dataverse), then cs_clone_agent bot=<id or schema name> outputDir=./support-agent. The result is a sync-connected workspace with
agent.mcs.yml, settings.mcs.yml, topics/, knowledge/, actions/, trigger/,
variables/, workflows/ and the connection references. cs_describe_workspace inventories
it and ends with next steps.
Change it. Components are found by name, file stem or path. cs_edit_topic changes trigger
phrases, priority and nodes (by position or id); cs_edit_tool changes descriptions, inputs and
the connection; cs_edit_knowledge changes a site or a trigger condition;
cs_remove_component deletes a topic, knowledge source, tool, trigger or variable and prunes
the connection reference nothing else uses, noting any redirect left dangling. cs_update_agent
and cs_update_settings cover the agent's own settings. Adding works as in the new-agent flow.
Every edit keeps the file header the extension expects.
Review and merge. cs_review_agent, then cs_pull to bring down what colleagues changed in
the portal (pac's three-way merge), then cs_validate.
Push. cs_push confirm=true. If a portal change and a local edit touch the same component
the push is blocked; cs_pull resolves it, force: true overrides it.
Commit. Keep the workspace in git and commit after every pull (the tool result reminds you). Portal drift then shows up as a diff you can review: accepting it is a commit, rejecting it is a push of the local version.
Around that loop: cs_delete_agent and cs_delete_solution remove things from the environment
(confirm); cs_extract_agent_template and cs_create_agent_from_template turn one agent into a
template for more; cs_extract_translations and cs_merge_translations do the localisation round
trip (.resx or .json, with whatIf); cs_quarantine_agent takes an agent out of service and back.
Copilot Studio agents can call any connector in the environment (more than a thousand Microsoft-published ones plus custom connectors), MCP servers exposed through connectors, cloud flows, AI Builder prompts, other agents, and a few rarer kinds. The server knows the kinds from the YAML schema and the instances from the environment, which is the only source that knows what exists there.
Find the connector. cs_list_connectors search=ServiceNow lists the environment's connector
registry, the same list the portal's Add a tool shows, with MCP servers flagged. Without a
sign-in it falls back to an offline seed generated from the public connector reference (display
name to shared_ id, no operations): a starting point, not proof the connector is enabled for
you.
Find the operation. cs_describe_connector connector=shared_service-now operation=incident
turns the connector's OpenAPI definition into operations with operationId, required and
optional parameters and response fields; x-ms-agentic-protocol: mcp-streamable-1.0 marks MCP
endpoints. Definitions are cached under .cs-catalog/<environment>/ so later calls are offline.
Add the tool. cs_add_tool takes a typed spec for a connector action, an MCP server, a cloud
flow, an AI Builder prompt (cs_list_prompts shows them), a connected agent or a child agent,
and a raw type for the rest (AI plugin, Bot Framework skill, client action, computer-use
agent). With the definition cached it checks the operationId, fills the automatic inputs from
the operation's required parameters, and writes the YAML under actions/ plus a
connection-reference stub. If you have not named a connector or operation yet the call comes
back as a question with the ranked candidates.
Connect it, once, in the portal. A connection is an authorised link that only the portal can
create (the one exception is a service-principal Dataverse connection, which
cs_create_connection makes). After cs_push, open the tool under the agent's Tools, Connect,
then cs_pull. cs_validate warns about tool files whose operation is not in the cached
definition, and cs_review_agent flags tools whose description will not let the orchestrator
pick them.
A unit test compares the schema's list of tool kinds with the server's table, so a schema update
that introduces a new kind fails the build until the kind is classified. Flows as tools are either
a scaffold (cs_add_flow, experimental) or a real flow built with the
flow builder and referenced from the agent.
Publish. cs_publish confirm=true is the Publish button, through pac copilot publish or
the Dataverse PvaPublish action polled until publishedon moves.
Chat. cs_chat utterance="..." sends one utterance to the published agent and returns the
reply; pass the conversationId back for the next turn. With transport: auto the server reads
the agent's authentication mode: no-auth and manual-auth agents go through DirectLine (the token
endpoint of a published agent is anonymous, so no app is needed); an agent with integrated Entra
authentication goes through the Copilot Studio client SDK and needs your own app id with the
CopilotStudio.Copilots.Invoke scope (clientId, or CPS_CLIENT_ID).
Make it repeatable. cs_run_conversation_tests runs a YAML file of utterances and
expectations through the same chat path and reports what failed. Expectations cover the
wording and what the agent did: usedTool, notUsedTool, usedTopic, notUsedTopic and
citedKnowledge read the topic, tool and knowledge attribution from the activities, so a test
can tell a real tool call from an answer that merely reads correctly. Every result, and every
cs_chat reply, reports the observed topic, tool and citations; an expectation that cannot be
judged (no attribution in the activities) says so rather than failing the agent. The
attribution key names come from documentation and are unverified live;
docs/test-verification.md is the runbook that settles them.
Evaluate. The portal's Evaluation feature runs a test set of questions against the agent and scores each answer. The one thing its API cannot do is create the test set, so the loop is:
cs_create_test_set_csv suggestFromWorkspace=true writes the CSV in the portal's import
format (max 100 cases), seeded from your topics and knowledge.
Import it once in the portal's Evaluation tab.
cs_list_test_sets, then cs_run_evaluation confirm=true wait=true, then
cs_get_evaluation_run for per-case results with pass and fail buckets;
cs_list_evaluation_runs for the history.
flowchart TD
A["cs_create_test_set_csv"] --> B["portal: Evaluation > Import CSV"]
B --> C["cs_list_test_sets"] --> D["cs_run_evaluation confirm wait"]
D --> E["cs_get_evaluation_run"] --> F{"failures?"}
F -- yes --> G["fix topics / instructions / knowledge"] --> H["cs_push confirm"] --> D
F -- no --> I["cs_publish confirm"]Once people use the agent, the transcripts are the best source of test cases and of the questions
it cannot answer. Copilot Studio stores every session in the Dataverse conversationtranscript
table; the server reads it and never writes.
cs_list_transcripts lists sessions in a window: when, how many turns, the first question, the
topics and tools that fired, how it ended.
cs_get_transcript returns one session's full turn list with the topic and tool attributed to
each turn.
cs_summarize_transcripts aggregates a window: outcomes, escalation rate, sessions that matched
no topic, the top topics and tools, and the questions behind the failures.
cs_test_set_from_transcripts builds the Evaluation import CSV from questions people actually
asked, failures first, so the next evaluation run covers what went wrong.
Copilot Studio does not report whether a conversation succeeded. The outcome is this server's
reading of the transcript (an escalation, the agent saying it could not answer, a user turn with no
reply); resolved means nothing marked the session as failed, not that the user was satisfied.
Every result repeats that caveat, and cs_guide transcripts walks the loop from a summary to one
transcript to a regression test set. Transcripts hold what users said to the agent, so the
signed-in user needs a role that grants read on that table and results are customer data.
Unverified against a live tenant.
Makers can keep editing an agent in Copilot Studio after it was cloned; nothing stops them and the
platform sends no notification. Every portal edit lands in Dataverse rows: the bot row for
settings and instructions, and one botcomponent row per topic, knowledge source, tool, trigger
and variable, each with a modified-on stamp and the user who changed it. The server uses those rows
to see drift without a re-scan, and a clone to confirm it when the details matter.
Sync stamp. cs_clone_agent, cs_pull, cs_push and cs_create_agent (with
environment) write .mcs/cs-sync.json: a fingerprint of every workspace file and, when a
Dataverse sign-in is cached, the modified-on stamp of every component. cs_describe_workspace
shows the last sync.
Quick check. cs_check_drift (default mode: quick) reads the bot row and its component
rows and compares them with the stamp: which components were modified, added or removed in the
portal, by whom and when, whether the agent settings changed, and whether the live agent has
unpublished changes. Each component is mapped to its workspace file; when that file also changed
locally the entry is a conflict. Seconds, no pac; needs cs_login.
Full check. cs_check_drift mode=full runs pac copilot clone into a temporary folder and
classifies every file three ways against the stamp: local-modified, remote-modified,
both-modified (conflict), added or deleted on either side, with unified diffs. Use it when the
quick check reports drift and you want the exact content, or when there is no Dataverse sign-in
(only the pac profile is needed). Uploaded knowledge files are covered here, not in the quick
check.
Push preflight. The cs_push dry run includes the quick check, so the caller sees "three
components changed in Copilot Studio since your last pull" before confirming. With confirm,
the push is blocked when a portal change and a local edit touch the same component; cs_pull
(pac's three-way merge) resolves it and force: true overrides it.
Git as the ledger. Commit after every cs_pull; cs_check_drift reports whether the
workspace is in a repository and how many of its files are uncommitted.
Limits. The quick check does not see connections (a maker connecting a tool is expected, and
connection ids are ignored in every comparison), uploaded knowledge files, channel configuration or
the security group. When the stamp has no per-component baseline (no Dataverse sign-in at sync
time) it falls back to the sync time with a two-minute margin, so edits made right after a sync
count as the sync itself. The component query has not been verified against a live environment
yet; see docs/STATUS.md.
Flows are built from a step spec, the way topics are, so you do not have to write Logic Apps JSON
by hand. cs_build_flow_definition composes the definition locally and returns it together with
the connection references it needs; cs_create_flow takes the same spec and creates the flow in an
environment or a solution; cs_update_flow takes it and replaces the definition of an existing
unmanaged flow, keeping its connection references.
A spec is a trigger plus steps that run in order:
Trigger | For |
| the flow a Copilot Studio agent calls as a tool, with typed inputs and a response |
| started by a person or by an HTTP request |
| a schedule |
| a connector event, such as a Dataverse row being created |
| any other trigger, written verbatim |
Step | Emits |
| a connector operation ( |
| an HTTP call |
| branching, looping and grouping, with their own nested steps |
| variables and intermediate values |
| end the run with a status |
| what an agent-callable or HTTP flow answers with (added automatically when you give |
| any other action, written verbatim |
The builder chains runAfter so each step waits for the previous one, normalises action names the
way Power Automate does, and collects one connection reference per connector used, reusing it
across steps. Expressions are Logic Apps expressions, not Power Fx: @{triggerBody()?['orderId']},
@body('List_rows')?['value']. Connector ids and operation ids come from cs_list_connectors and
cs_describe_connector; an operation's parameters are exactly the parameters of a connector
step.
Around the builder: cs_list_flows shows the flows in the environment with state, owner and
connection references; cs_get_flow returns one with its full definition; cs_delete_flow removes
one for good; cs_list_flow_runs, cs_get_flow_run and cs_run_flow read the run history and
start a manual run through the Power Automate service (a separate sign-in, cs_login scope='flow';
the signed-in user must own or co-own the flow).
Bind the connections. A connection reference names a connector; a connection is one person's
authorised account for it, and until the two are joined the flow cannot run. cs_bind_flow_connection
joins them: with one reference and one usable connection it needs nothing but the flow id, and it
asks which when there is a choice. It writes whichever of the two shapes the flow uses - a flow
built outside a solution names its connection directly, while one that arrived in a solution points
at a connectionreference row - and activate: true turns the flow on in the same call.
cs_set_flow_state turns one on by itself once it is bound.
Work out why a run failed. The run list says a run failed and nothing more.
Tool | Answers |
| Why did this run fail? A failed connector action carries no error message of its own - the message is in the action's outputs, behind a link that expires after a few days - so this fetches it, says whether the fault is the connector, an expression or a timeout, and shows the inputs the action was called with next to the outputs of the actions that ran just before it. |
| It worked yesterday. Diffs the failed run against the most recent successful one and names the action where they part company. With |
| It fails sometimes. Failure rate, duration median and 90th percentile, and which actions the failures land on. One action responsible for most of them is a broken step; failures spread across many point at the connection, throttling or the system being called. |
A trigger that failed means the flow never ran at all, so the fault is in the trigger's connection or its parameters rather than the logic. Run detail ages out: inputs and outputs are kept for a limited time, so diagnose a failure while it is recent.
Two things the builder cannot do for you. The connections themselves must exist in the target environment before anything can be bound to them, which is why a new flow is created switched off. And the definitions follow the Logic Apps schema and exported solutions rather than a verified round trip, so import one and open it in Power Automate before trusting the shape.
Per-agent sync stays bound to the environment the agent came from. Moving to test or production is a solution export and import, and the server makes that a pull, a settings file and a deploy.
See what you are moving. cs_list_solutions, then cs_describe_solution exports, unpacks
and inventories: agents, bot components, flows, connection references, environment variables,
custom connectors.
Pull it. cs_pull_solution exports the solution unmanaged and managed, unpacks it to
src/, writes solution.json (the manifest the deploy reads), creates
deployment-settings.json and clones every agent into agents/. A full pull runs for minutes,
so pass background: true and follow it with cs_job_status; the outcome also lands in
pull-job.json in the target directory.
Map the target. cs_list_connections on the target environment shows the connections that
exist there; cs_create_deployment_settings maps each connection reference to one of them, sets
the environment variable values for the target and, per agent, the Entra security group that may
use it.
Deploy. cs_deploy_solution confirm=true imports into the target with the settings file and
runs pac copilot publish on every agent (publishAgents, default on). It refuses to import
while any connection reference is unmapped unless you pass allowUnmapped: true. If you edited
src/ by hand, cs_pack_solution first.
Quality gates and alternatives on the same path: cs_check_solution runs Solution Checker before a
deploy; cs_set_solution_version, cs_solution_online_version and cs_upgrade_solution handle
release numbering and staged upgrades; cs_publish_customizations publishes everything in an
environment; cs_list_pipelines and cs_deploy_pipeline use Power Platform pipelines instead of
a direct import; cs_init_solution_project, cs_clone_solution, cs_sync_solution,
cs_add_solution_reference and cs_add_solution_license keep a source-controlled solution
project (.cdsproj); cs_add_solution_component adds an existing component to a solution.
Plan for these before calling the copy "1:1":
Connections are not part of a solution. A solution carries connection references; the
connections themselves (the authorised links to SharePoint, Outlook, Dataverse, MCP servers, ...)
must already exist in the target environment, created and consented by a user there.
cs_create_connection is the one exception and only covers service-principal Dataverse
connections. With allowUnmapped: true the tools stay unbound until someone binds them in the
target portal.
Cloud flows land switched off when their connection references cannot be resolved. Bind the
connections, then cs_list_flows shows which are not activated and cs_set_flow_state switches
each on; the portal is not needed for that step.
Environment variables need target values. The settings file lists every variable; leave a value empty and the target inherits the default from the solution, which is usually a dev value.
Who can use the agent is per environment. The settings file has a CopilotAgents section
with an AadGroupId per agent (verified with pac 2.11.2). Map it to the target's Entra group
(copilotAgents in cs_create_deployment_settings) or set access in the target portal after
import; an all-zero id means no group is set.
Some agent content lives outside the solution. Uploaded knowledge files, Dataverse tables used as knowledge, SharePoint permissions, and channel configuration (Teams, web, Microsoft 365 Copilot) are environment-specific. After import, check knowledge sources and re-publish to channels in the target portal.
Managed vs unmanaged. cs_pull_solution exports both. Deploy managed for downstream
environments and keep unmanaged only for development; a managed import cannot be edited in place
in the target.
Per-agent sync does not cross environments. Workspaces from cs_clone_agent or
cs_pull_solution push back to their source environment only. Edit the agents/<name>
workspace, push to the source, then pull and deploy the solution again.
When the same solution is promoted through development, test, acceptance and production, the question is whether each stage still holds what the previous one holds. The platform has no cross-environment diff, but every input is reachable, so the server captures each environment into a snapshot folder and compares snapshots offline.
Snapshot each stage with cs_snapshot_environment (or all at once with
cs_compare_environments, which takes an ordered chain and compares each adjacent pair). A
snapshot folder contains:
snapshots/TEST/
snapshot.json label, environment, time, solution version and managed flag,
agents with publish state, flows, connection references,
environment variables, notes
agents/<Agent name>/ the agent as YAML, from pac copilot cloneAgents are cloned rather than exported as a solution, because a managed solution cannot be
exported from test or production. Flows, connection references, environment variables and
publish state come from Dataverse and are included when you are signed in with cs_login;
otherwise the snapshot notes that they were skipped.
Compare adjacent stages with cs_compare_snapshots (DEV vs TEST, TEST vs ACC, ACC vs PROD).
Each comparison writes <A>-vs-<B>.md and .json.
Read the verdict. A report starts with DRIFT or no drift, then lists the drift, the
expected differences, and tables per layer with unified diffs for changed agent files.
Act on it. Drift in agent YAML means the later stage is behind or was edited in place: promote again with the solution flow above. Unbound connection references, missing flows, or variables without a value are deployment-settings problems: fix the settings file and redeploy.
Keep history. Snapshot folders are plain files; commit them (without .mcs/ state) to get
a timeline per stage.
What counts as drift, and what is an expected difference between stages:
Layer | Drift | Expected difference (reported, not drift) |
Solution | version differs, missing in a stage | managed in later stages, unmanaged in development |
Agent YAML (topics, instructions, knowledge, tools, triggers, variables) | any changed, added or removed file after normalisation | ids, audit info, version fields, connection ids inside |
Publish state | modified after last publish in any stage (unpublished changes) | |
Flows | missing in a stage, on/off state differs | |
Connection references | missing, connector differs, unbound in a stage | bound to a different connection per stage |
Environment variables | missing, no value in a stage | different values per stage (drift only with |
Authentication mode | differs between stages |
Pipeline gate. cs_compare_snapshots and cs_compare_environments accept failOnDrift; the
tool result is then an error, which a scripted MCP client or a pipeline step can turn into a failed
job. A typical gate before promoting TEST to ACC:
cs_snapshot_environment label=TEST environment=<test id> dir=snapshots/TEST solution=<name>
cs_snapshot_environment label=ACC environment=<acc id> dir=snapshots/ACC solution=<name>
cs_compare_snapshots a=snapshots/TEST b=snapshots/ACC failOnDrift=trueCaveats: all stages must be reachable from the active pac auth profile (for chains that span
tenants, run pac auth select between stages and snapshot them one by one); whether
pac copilot clone succeeds on a managed agent is unverified live (the fallback is reading the same
component definitions through the Dataverse Web API); uploaded knowledge files and channel
configuration are listed by name and size only; without a Dataverse sign-in the comparison covers
solution version and agent YAML only, and the report says so.
Administration runs as the admin account (two accounts): pass
profile, or set CPS_ADMIN_PROFILE once. Every change goes through the same dry run and
confirm; reset, delete, copy and restore destroy or overwrite whole environments, and the dry run
says what will be lost.
Back the configuration up to files. cs_backup_tenant writes the whole tenant configuration
to a folder: tenant settings, environments, DLP policies, environment groups, service principals,
registered applications, templates, and per environment its details, solutions, agents,
connections, security roles and platform backups. Raw output is kept next to parsed rows, and a
capture that fails is isolated so the rest of the backup still lands.
Read and change the tenant. Environments and their operations in progress, tenant settings
(read to a JSON file, change one), DLP policies (which connectors may be combined), environment
groups, security roles, service principals and registered applications, managed-environment
governance, administration mode and backup retention, and the environment lifecycle: create,
copy, back up, restore, reset, delete. Each is one cs_admin_* tool
(list).
Onboard a team into a new environment. cs_admin_create_environment (slow; pair it with
background: true and cs_job_status), then cs_admin_assign_users with a CSV:
UPN,Security Roles,Business Unit
alice@contoso.com,"System Customizer,Basic User",Sales
bob@contoso.com,Environment Maker,pac takes one user and one role per call, so that roster is five calls; the tool expands it,
shows you every user-and-role pair in the dry run, and runs them under one approval. Rows are
independent, so a mistyped UPN is reported and the rest still run. Prefer
cs_admin_assign_group when the roster is really a group: binding an Entra group to a role is
one call however many people are in it, and new joiners inherit access. Role names are
per-environment (cs_admin_list_security_roles against the new one), and a user who has not
been provisioned into the environment yet cannot hold a role there.
The Microsoft 365 agent catalogue. cs_list_agents reads one environment's bots table and
stops at the Power Platform boundary. The catalogue (Microsoft Graph, a separate sign-in with
cs_login scope='graph') is tenant-wide and answers the question that follows cs_publish: did
the agent actually reach anyone? cs_list_org_agents reports who each agent is available to,
where it is deployed and whether it is blocked, filtered by platform, host, element type or
last-modified date; cs_get_org_agent returns one entry in full; cs_block_org_agent blocks an
agent for everyone in the tenant or lifts the block, and cs_reassign_org_agent hands it to a
new owner when the old one leaves (both confirm). Needs a Microsoft Agent 365 licence, is
global-cloud only, is unverified against a live tenant, and block and reassign exist only on
Graph beta.
Every pac command without a tool of its own is reachable through cs_pac: read-only commands run
immediately, the others return a dry run and need confirm. The pac groups outside Copilot Studio
work (application, canvas, catalog, code, data, managed-identity, model, modelbuilder, package,
pages, pcf, plugin, power-fx, telemetry, test, tool) are deliberately left there.
An agent's settings live in two files, and the server reads, validates and pushes both. The table
maps what the portal shows to the field and the tool argument that writes it. Everything here is a
local file change, shown before it is made and written only with confirm: true; cs_push applies
it, and cs_publish makes it live. instructions is capped at 8000 characters by the product, and
the preview counts them.
agent.mcs.yml (the agent definition), written by cs_update_agent:
Portal | Field | Argument |
Instructions |
|
|
Responses: how answers are worded and formatted ("Response formatting") |
|
|
Responses: response mode |
|
|
Conversation history the agent sees |
|
|
Capabilities: web browsing, code interpreter, image generation, Teams / SharePoint / email / meeting / people search |
|
|
General knowledge: may the model answer beyond your knowledge sources |
|
|
Content moderation |
|
|
File analysis, semantic search |
|
|
Model |
|
|
Conversation starters |
|
|
Display name |
|
|
Values are checked against the authoring schema, so a response mode or moderation level outside the allowed set is refused rather than written.
settings.mcs.yml (how the agent runs), written by cs_update_settings with dot paths, for
example {"configuration.settings.GenerativeActionsEnabled": true}:
Portal | Path |
Generative orchestration on or off |
|
Authentication |
|
Language |
|
Agent can be called by other agents |
|
Analytics, telephony, voice, network |
|
cs_update_settings refuses to change authoringModel, recognizer.kind and template,
because the tooling depends on them. cs_lookup_schema shows any other field the schema allows,
and cs_validate checks whatever you write by hand.
One caveat: these field names come from the authoring schema, not from a round trip through a live
agent, so which portal control maps to which field is inference. Set one in the portal, run
cs_clone_agent and compare if you need certainty.
The server signs users in with an MSAL public client (interactive browser or device code). It
never uses client secrets, so every permission it needs is a delegated permission acting as the
signed-in user. Application permissions are listed below only where Microsoft offers them, for
people who build a headless pipeline on top of the same APIs. How cs_login behaves inside an MCP
client is described under The first session.
Do you need your own app registration?
Situation | App registration needed? |
| No. |
Cloud tools with the default client id ( | No. The server uses the first-party VS Code client id |
Same tools, but your tenant blocks that id (app consent policy, conditional access, "user assignment required") | Yes. Create the registration below and set |
| Yes, always. The first-party id does not carry |
Headless CI (service principal, no user) | Not supported by this server today (public client only). For pipelines use |
Permissions for your own app registration (Entra ID > App registrations > API permissions > "APIs my organization uses"):
Used by | API to pick in Entra | Permission | Delegated or application | Notes |
| Power Platform API (app id |
| Delegated is what this server uses. An application permission of the same name exists for confidential clients (Microsoft 365 Agents SDK); not used here. | Admin consent is normally required. Redirect URI |
| Power Platform API | Token scope | Delegated only. Power Platform API has no application permissions; service principals get access through RBAC roles instead. | Verified with the first-party id by Microsoft's own tooling. Not yet verified with a custom registration; if calls return 403, the signed-in user needs maker access to the agent. |
| PowerApps Service (app id |
| Delegated. | Calls the BAP environments API ( |
| Dynamics CRM (Dataverse, app id |
| Delegated. There is no application permission; server-to-server access to Dataverse means an application user with a security role in each environment. | The user still needs a Dataverse security role that can read and publish bots (System Customizer or a Copilot Studio maker role). The drift checks only read the |
| Microsoft Flow (Power Automate service, app id |
| Delegated. | A separate resource from Dataverse and the Power Platform API, so it needs its own consent: sign in with |
| Microsoft Graph (app id |
| Delegated is what this server uses; an application permission of the same name exists for reads. | The Microsoft 365 agent catalogue, a different resource again: sign in with |
| Microsoft Graph |
| Delegated only. Microsoft offers no application permission for these two actions. | Same licence and cloud limits as above; sign in with |
| Power Platform API | Token scope | Delegated only. | Same resource as the evaluations. Consent bypass is an admin setting on the agent, so the write (and possibly the read) needs a Power Platform or Copilot Studio admin role; the manifest download needs maker access and an agent published to the Microsoft 365 / Teams channel. All three follow the published reference and are unverified against a live tenant. |
| none | none | not applicable | The DirectLine token endpoint of a published agent is anonymous. |
| none | none | not applicable | Microsoft's own app; |
Steps for your own registration:
Entra ID > App registrations > New registration. Single tenant. Under Authentication add the
platform Mobile and desktop applications with redirect URI http://localhost (the loopback
MSAL uses for cs_login interactive). Set Allow public client flows to Yes if you plan to use
cs_login with mode: device_code.
Add the permissions from the table. If Power Platform API does not appear when you search
by name or by the id above, its service principal is missing from your tenant; create it with
az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43 (or
New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43) and search again.
Grant admin consent for the tenant, or let each user consent interactively on first sign-in.
Put the ids in the MCP server environment: CPS_CLIENT_ID=<application (client) id> and
CPS_TENANT_ID=<directory (tenant) id>. cs_chat also accepts clientId per call.
All environment variables are optional:
Variable | What it does |
| the agent workspace to start in (VS Code: |
| the Entra tenant and app registration for |
| defaults for cloud tools when the workspace carries no sync metadata; explicit arguments win, then workspace metadata, then these, then a BAP lookup |
| the pac auth profile for maker commands and for admin commands (two accounts) |
| withhold every environment-changing tool (approval) |
| trim the tool list: presets and comma-separated names with |
| override the token scopes for the Power Automate service and Microsoft Graph |
| token cache location, the pac executable, the .NET root |
The full tool list is 148 tools, about 50k tokens of schema before any work starts. A frontier
model copes; a smaller one spends most of its context on the menu and chooses worse from it. Set
CPS_TOOLS to a preset in the server's environment, or let the user choose during the session:
cs_init returns a toolPresets block with the question, the option table and a live count per
preset, and cs_set_tool_preset applies the answer.
Preset | Tools | When to use it |
| 148 | everything; a large model, or you do not know yet what the task needs |
| 34 | build or change one agent and get it live: the usual choice |
| 25 | write and check files only; no sign-in, nothing reaches an environment |
| 49 | tenant administration as the admin account, plus |
| 25 | pull, deploy and compare solutions, and bind the flows an import left switched off |
Nothing is removed: a preset only changes which tools are offered, and cs_init, cs_guide,
cs_set_tool_preset and cs_job_status survive every preset so a session can always change its
mind. cs_pac is in core, admin and solutions so any pac command a preset hides is still
reachable, and cs_init says that a missing tool is hidden rather than absent. Presets compose
with each other and with globs: CPS_TOOLS=core,cs_admin_*, or
CPS_TOOLS_EXCLUDE=cs_*_pipeline,cs_env_*,cs_*_auth_profile. The SDK sends
notifications/tools/list_changed on a switch, so a client that honours it sees the shorter list
at once; one that caches the list needs a restart. Runtime switching can only narrow what was
registered at startup, so leave CPS_TOOLS unset if you want every preset available to choose
from.
A tool list this long is a routing problem: the descriptions decide whether "why did my flow fail
last night?" reaches cs_explain_flow_run or something that answers a different question. The
package ships the check, so you can measure it against your own preset, your own model and your
own phrasings rather than trusting the numbers here:
npx copilot-studio-mcp-routing-eval --dry-run # free: shows the corpus and the cost
npx copilot-studio-mcp-routing-eval --preset core --repeat 3 --yes
npx copilot-studio-mcp-routing-eval --cases ./my-questions.json --yesIt puts the tool list in front of a model exactly as your client sees it, one utterance at a time,
and scores the first tool named. --cases takes your own file in the shape of the bundled
reference/routing-cases.json, which is rather the point: the questions your users actually ask
are better evidence than the ones shipped here. With ANTHROPIC_API_KEY set it calls the Messages
API with the tool list as a cached prefix and a run costs cents; without one it falls back to the
claude CLI and the sign-in that machine already has. Either way a run calls a model once per
case and spends real money, so nothing happens without --yes.
Read it with --repeat 3, never a single run. Measured on Haiku 4.5, the score moves by two
cases between runs of an identical build, and a third of the cases answer differently each time.
One run will happily tell you a change helped when it did not. The report separates the cases that
are always misrouted, which are worth acting on, from the ones that flap, which prove nothing.
The handshake instructions are written for a smaller model: one rule per line, an explicit trigger before each instruction, and a section naming the failures seen in the first live run (a call cut off at the client's ~60s limit, a tool missing because the server binary was stale, a cloud tool failing for want of a sign-in, pac reporting failure while exiting 0) with the action for each.
Capability | How | Status |
Agent as files, sync both ways |
| official, GA |
Topics, knowledge, tools, triggers, flows as YAML | workspace layout of the VS Code extension and | official |
Local validation | JSON schema from microsoft/skills-for-copilot-studio (MIT) + structural checks | this server |
Run evaluations, read results | Power Platform API | official, GA, standard harness |
Chat with the published agent | DirectLine v3 (no-auth / manual-auth agents) or Copilot Studio client SDK (Entra SSO) | official |
Publish |
| official |
Read, create, change and delete cloud flows | Dataverse | official API, shapes unverified live |
Bind a flow's connections |
| official API, shapes unverified live |
Flow run history, start a run | Power Automate Process Simple API | the service the portal calls, unverified live |
Explain a failed run, diff it against one that worked, score a flow's reliability | the same API's per-run actions route, plus the SAS-signed content links it returns | this server, unverified live |
Portal drift since the last sync |
| this server |
Tenant configuration to files |
| this server |
Hard limits the server works around rather than hides:
Evaluation test sets cannot be created through the API. cs_create_test_set_csv writes
the CSV the portal imports (max 100 cases); after one import, runs and results are automated.
Connector, MCP and prompt tools need a connection that only the portal can authorise.
cs_add_tool writes the YAML and the connection-reference stub and returns the portal step.
The one exception is a service-principal Dataverse connection, which cs_create_connection
can create. The same limit is why a new cloud flow is created switched off: bind its
connections, then cs_set_flow_state.
Evaluations and topic YAML are standard-harness features. GitHub Copilot harness agents
(--authoring-mode cli-copilot) get init / pack / import / instructions / chat only.
Copilot Studio does not report whether a conversation succeeded. The transcript tools derive an outcome from the activities. Treat the rates as a place to look, and read the transcript before acting.
A workspace that was never connected to an environment packs less. Verified against pac
2.11.2: pac copilot pack on a workspace from pac copilot init without --environment
packages settings, agent and topics only and rejects knowledge/, actions/, tools/,
trigger/, variables/, workflows/ and connectionreferences.mcs.yml. Those folders are
handled by pac copilot push from a sync-connected workspace (clone, or init with an
environment). The authoring tools tell you when you are in a pack-only workspace.
The Power Platform CLI ships a built-in MCP server (pac copilot mcp --run, preview, named
"Power Platform Management MCP Server"). It is a natural-language front end to pac itself: each
of its tools runs one pac command. Probed on pac 2.11.2 it exposes 70 tools, of which exactly one
is about Copilot Studio (copilot_publish); 51 are tenant administration, managed identity,
model-driven apps and generated pages, Power Pages, code apps and code generation.
pac MCP server ( | copilot-studio-mcp (this repo) | |
Purpose | run pac commands in natural language; tenant and environment administration | build, test, ship and maintain Copilot Studio agents from the editor |
Copilot Studio commands |
| init, clone, pull, push, pack, publish, status, list, delete, templates, translations, quarantine, AI Builder instructions |
Authoring | none | topics, knowledge sources, tools (connector / MCP / flow / prompt / agent), triggers, variables, and the agent's own settings as YAML; day-two edit and remove; schema validation (744 definitions); rules-based review with a score |
Testing | none | evaluation test sets and runs (Power Platform API), chat through DirectLine or the client SDK, local conversation tests, production transcripts |
ALM | solution list, export, import, check | pull a whole solution with a deployment settings file and redeploy it 1:1, Solution Checker, versioning, staged upgrades, pipelines, DTAP snapshots and comparison |
Drift | none | portal changes since the last sync (quick Dataverse check, full clone diff) and a push preflight that blocks on conflicts |
Safety | no dry run in the server; the client's approval prompt is the only gate | every environment-changing tool returns a dry run until |
Tenant administration | admin commands as native tools | the admin commands plus |
Cloud flows | none beyond raw pac | list, read, create, rebuild, switch on or off, run history, and a step-based definition builder |
Guidance | tool descriptions | usage instructions in the handshake, |
Other pac groups | managed-identity, model, pages, code, modelbuilder as native tools | reachable through |
Sign-in | pac auth profile | pac auth profile, plus MSAL for the APIs pac does not cover (evaluations, Dataverse reads, environments, chat) |
Tool list | fixed | presets and |
Both are stdio servers and can be registered side by side: pac's for tenant administration, this one for agent work. One practical note: pac's server prints a non-JSON line on stdout at startup, which strict MCP clients may reject.
Sources: Use Power Platform CLI with built-in MCP server
and a tools/list probe of pac 2.11.2 (2026-09-07).
flowchart LR
VS["VS Code / GitHub Copilot"] --> TOOLS
CC["Claude Code"] --> TOOLS
subgraph SERVER["copilot-studio-mcp"]
TOOLS["MCP tool call"] --> SYNC["Sync layer: pac copilot, pac solution, pac admin"]
TOOLS --> AUTH["Authoring layer: YAML + schema validation, flow builder"]
TOOLS --> CLOUD["Cloud layer: evaluations, publish, chat, flows, drift"]
end
AUTH --> WS["Agent workspace on disk: topics, knowledge, actions, workflows"]
SYNC --> WS
SYNC --> DV["Dataverse / Copilot Studio"]
SYNC --> BACKUP["Tenant backup and solution folders on disk"]
CLOUD --> PPAPI["Power Platform API"]
CLOUD --> DV
CLOUD --> FLOW["Power Automate service: flow runs"]
CLOUD --> DL["Published agent: DirectLine or SDK"]The cloud workflows were built from documentation and the published schema; phases A to F
received a first live verification on 2026-09-08. docs/verify.md is the current follow-up list.
docs/live-verification.md is the full runbook: phases A to D are read-only and retire most of the
open questions without touching the tenant, E to G write and say so. docs/verification-template.md
is the results file to fill in, and scripts/redact-verification.mjs replaces GUIDs, org URLs,
emails and tokens with stable pseudonyms so a result can be shared from a public repo.
docs/STATUS.md is the full historical record. docs/test-verification.md is the runbook for the
feedback loop (static checks, behavioural tests, transcripts, closing the loop); its phase 1
settles whether live activities carry the topic, tool and citation attribution the conversation
tests read.
git clone https://github.com/jgt87/copilot-studio-mcp.git
cd copilot-studio-mcp
npm install
npm run build # dist/index.js is the server: register it as "command": "node", "args": ["<repo>/dist/index.js"]
npm test # build + unit tests (fixtures, no network)
node scripts/smoke.mjs # drive the built server over stdio
node scripts/oracle-pack.mjs # pac copilot init + authoring tools + pac copilot packreference/bot.schema.yaml-authoring.json and reference/templates come from
microsoft/skills-for-copilot-studio (MIT, see reference/LICENSE.skills-for-copilot-studio.txt).
Fixtures under test/fixtures/pac-* were generated with pac copilot init.
MIT licensed.
EXPERIMENTAL: write workflows//metadata.yaml + workflow.json for a flow with the 'when an agent calls the flow' trigger and a response, optionally exposing it as a tool. Format follows the schema's CloudFlowDefinition and the Power Automate solution JSON; verify with cs_pack and in the portal after push. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| inputs | No | ||
| actions | No | Extra Power Automate actions (name -> definition) inserted before the response | |
| addTool | No | Also create actions/<name>.mcs.yml invoking this flow | |
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| outputs | No | ||
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well on the highest-risk trait: it states that the first call is non-mutating and returns a diff for approval, and that confirm: true is required to actually write. It still omits overwrite/collision behavior and whether existing files are destroyed, so it is not fully transparent for a write 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?
Front-loaded with the EXPERIMENTAL marker and the concrete artifacts written, then the confirmation protocol. Four dense sentences with little waste, though the confirm explanation partially restates the schema's own confirm description.
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 9-parameter write tool with nested objects and no output schema, the description usefully describes the preview return shape ('the files it would write, as a diff against what is there now'), which the schema cannot convey. Remaining gaps are overwrite semantics and the meaning of several 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 only 44%, so the description must compensate. It clarifies confirm and addTool (both already documented in the schema) and implies outputs via 'a response', but name, inputs, actions, overwrite, workspace, and description get no added meaning beyond the schema, leaving a real gap.
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?
Specific verb and resource: it names the exact artifacts it writes (workflows/<Name>/metadata.yaml + workflow.json) and the trigger it scaffolds ('when an agent calls the flow'). However it never distinguishes itself from close siblings such as cs_create_flow, cs_build_flow_definition, or cs_add_tool, so an agent cannot route between them from the description alone.
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 post-conditions for use (verify with cs_pack and in the portal after push) and explains the two-step preview/confirm invocation, which is genuine usage guidance. But there is no statement of when to prefer this over cs_create_flow or cs_build_flow_definition, and no prerequisites (workspace, auth profile) are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add knowledge as YAML: kind 'public-site' (Bing-scoped website, max 2 path levels), 'sharepoint' (direct folder URL), 'graph-connector' (Microsoft Graph connector via environment variable), or 'files' (copy documents into knowledge/files for upload on push). Dataverse, AI Search and SQL knowledge are portal-only. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | Yes | ||
| site | No | ||
| files | No | Absolute paths of documents (pdf, docx, txt, ...) | |
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No | ||
| connectionName | No | ||
| includeSubPages | No | ||
| triggerCondition | No | Power Fx condition restricting when this source is searched | |
| contentSourceDisplayName | No | ||
| connectionEnvironmentVariable | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it warns that the first call changes nothing, returns a diff for approval, and only writes when confirm: true is supplied. It does not cover overwrite behavior, permissions, or what happens to existing files beyond the diff preview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and kind semantics, then the preview/confirm workflow. It is dense but nearly every clause adds useful information, though a more structured format could improve scanability.
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 13-parameter mutation tool with no annotations and no output schema, the description covers the central workflow and key kinds well. It remains incomplete about many optional parameters and side-effect details that an agent may need before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 31% across 13 parameters. The description adds valuable meaning for kind and reiterates confirm, but leaves many parameters such as site, overwrite, connectionName, includeSubPages, and connectionEnvironmentVariable unexplained.
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 gives a specific verb and resource: adding knowledge as YAML, and enumerates the four supported kinds. It clearly distinguishes these from portal-only knowledge types, but does not explicitly differentiate from sibling tools such as cs_edit_knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains when to use each kind, notes that Dataverse/AI Search/SQL knowledge are portal-only, and describes the required two-step preview-then-confirm workflow. It could be stronger by naming sibling alternatives for editing existing knowledge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an existing component (an agent, flow, connection reference, environment variable, table ...) to an unmanaged solution by schema name or id and component type code. Runs 'pac solution add-solution-component' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| component | Yes | Schema name or id of the component | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| solutionName | Yes | Solution unique name | |
| componentType | Yes | Component type code or name (e.g. 29 for a flow / workflow, 10088 for a connection reference, 380 for an environment variable definition) | |
| timeoutSeconds | No | Default 600 | |
| addRequiredComponents | No | Also add the components it depends on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the two traits that matter most: this mutates a live environment and is gated behind confirm: true, returning a dry run without it. It also names the underlying 'pac solution add-solution-component' command and the auth profile used. It stops short of idempotency/duplicate handling, error behavior, or whether changes are reversible.
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 action and resource, then the mechanism and the safety gate. No filler and no repetition of the title.
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 11-parameter mutation tool with no annotations and no output schema, the description covers the action, the addressing scheme, the execution mechanism and the confirm gate. Parameter mechanics (async, background/jobId, timeout, cwd, profile resolution) are left entirely to the schema, which is acceptable given 100% coverage, but the description says nothing about outcomes or failure modes.
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 every parameter including componentType examples and confirm semantics is already documented in the schema. The description restates the same information ('by schema name or id and component type code') without adding syntax, formatting, or defaults beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Add an existing component ... to an unmanaged solution'), enumerates the component kinds (agent, flow, connection reference, environment variable, table) and the two addressing modes (schema name/id plus type code). This is clearly distinguishable from neighbors such as cs_add_solution_reference, cs_add_solution_license and cs_remove_component.
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 a concrete precondition for real use: the tool mutates a live environment and requires confirm: true, otherwise it is a dry run. It also anchors the operation to the active pac auth profile. It does not, however, name alternative tools or state when to prefer cs_add_solution_reference / cs_import_solution instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach license plan definition and mapping CSV files to a solution project (ISV licensing). Run in the solution project folder (cwd). Local file change only. Runs 'pac solution add-license' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 | |
| planMappingFile | Yes | CSV: Service ID, Component name | |
| planDefinitionFile | Yes | CSV: Service ID, Display name, More info URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this is a local file change only (not a tenant push), that it wraps 'pac solution add-license', and that it uses the active pac auth profile. It doesn't cover failure modes or exactly which project files are mutated, but the key side-effect profile is 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?
Three tight sentences: purpose first, then the operating constraint, then the side-effect and underlying command. No filler, and the most important constraint (local-only change) is stated plainly.
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 6-param tool with no output schema and no annotations, the description covers purpose, execution context, side effects, and the underlying CLI command. Return values are not needed since it is a local file change. Minor gap: no mention of what to do on validation failure of the CSVs.
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 six parameters including the two CSV files and cwd. The description only adds marginal meaning by clarifying that cwd should be the solution project folder. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (attach) plus the exact resources (license plan definition and mapping CSV files), scoped to a solution project with the ISV licensing context. It clearly distinguishes this from siblings like cs_add_solution_component or cs_add_solution_reference by naming the specific artifacts involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the operating context ('Run in the solution project folder (cwd)') and the ISV licensing scenario, which implies when to use it. However, it never names or contrasts with the sibling add-tools (e.g., cs_add_solution_component), leaving the agent to infer selection. Usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reference another project (plug-in, PCF, ...) from a .cdsproj so it is packed into the solution. Run in the solution project folder (cwd). Local file change only. Runs 'pac solution add-reference' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| path | Yes | Path of the referenced project | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It usefully discloses 'Local file change only' and that it shells out to 'pac solution add-reference' with the active auth profile, clarifying the side effect is a local file edit rather than a tenant mutation. It does not address idempotency, what happens if the reference already exists, or failure modes.
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 with the purpose front-loaded, then the cwd requirement, then the underlying command. Efficient and well ordered, though the final pac/auth-profile sentence partially duplicates information already implied by the profile parameter.
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 local-file mutation with no output schema, the description covers intent, execution context (cwd) and side-effect scope (local only), which is most of what an agent needs. It stops short of documenting return value or verification steps, but nothing critical is missing to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents cwd, path, profile, background and timeoutSeconds. The description reinforces cwd ('solution project folder') but adds no syntax or format meaning beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: reference another project (plug-in, PCF) from a .cdsproj so it is packed into the solution. It is concrete enough to distinguish from general component-adding tools, though it never names the closest sibling (cs_add_solution_component) to disambiguate explicitly.
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?
Gives a real prerequisite: 'Run in the solution project folder (cwd).' That orients the agent on how to call it. However it offers no when-not-to-use guidance and does not contrast with cs_add_solution_component or other add-* siblings, so the agent must infer the choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create actions/.mcs.yml. type 'connector': a connector operation (connectorId like shared_office365, operationId like SendEmailV2; use cs_list_connectors / cs_describe_connector to find them). type 'mcp': an MCP server exposed through a connector. type 'flow': a cloud flow by id. type 'prompt': an AI Builder prompt by model id (cs_list_prompts). type 'connected-agent': another Copilot Studio agent by schema name. type 'child-agent': a child agent's GPT component. type 'raw': any other TaskAction kind with the action object supplied. When the connector definition is cached, the operationId is checked and required inputs are filled from the catalog unless inputs are given. Connector and MCP tools need a connection that only the portal can authorise; the tool writes the connection-reference stub and returns the portal step. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| type | Yes | ||
| action | No | type raw: full TaskAction object with kind | |
| flowId | No | ||
| inputs | No | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| outputs | No | ||
| aiModelId | No | type prompt: AI Builder model id | |
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| connectorId | No | shared_<name> or a display name from the catalog | |
| description | Yes | Also used as modelDescription unless overridden; the orchestrator routes on it | |
| operationId | No | ||
| botSchemaName | No | type connected-agent | |
| connectionMode | No | Invoker = end user's connection; Maker = the maker's shared connection | |
| modelDescription | No | ||
| inputsFromCatalog | No | Default true: when no inputs are given and the connector definition is cached, add automatic inputs for the operation's required parameters | |
| connectionReference | No | Existing logical name from connectionreferences.mcs.yml | |
| gptComponentSchemaName | No | type child-agent |
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 that connector/MCP tools require a portal-only connection, that a connection-reference stub is written, that catalog caching auto-fills inputs, and that the first call is a no-op diff preview requiring confirm:true to actually write. This is exactly the operational context an agent needs before invoking a mutation.
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 file artifact, then type semantics, then the confirmation workflow — a logical order with little filler. It is dense and long, but for a 19-parameter tool nearly every clause carries 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 19-param, no-annotation, no-output-schema mutation tool, the description covers the write/preview protocol, the return format (diff against current file with character count), authorization prerequisites, and per-type parameter expectations. Nothing essential to calling it correctly 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 only 58%, but the description compensates by mapping types to parameters (connectorId/operationId for connector, flowId for flow, aiModelId for prompt, botSchemaName for connected-agent, gptComponentSchemaName for child-agent, action for raw) and by explaining the confirm/inputsFromCatalog behavior. Remaining ambiguity (outputs, overwrite, workspace) is not addressed, so it falls short of fully covering the gap.
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?
Opens with a concrete verb and artifact ('Create actions/<name>.mcs.yml') and then enumerates every accepted type with what each one means, so the agent knows exactly what this tool produces. It is clearly distinguishable from siblings like cs_add_flow or cs_edit_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives per-type routing guidance (cs_list_connectors / cs_describe_connector to find connector ops, cs_list_prompts for prompts) and explains the two-step preview-then-confirm workflow. It does not explicitly contrast itself with cs_add_flow or cs_edit_tool, so the alternative selection is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create topics/.topic.mcs.yml from a declarative spec: trigger phrases (or a system trigger) plus message / question / condition / redirect / setVariable / searchKnowledge / http / invokeFlow / end / raw nodes. Validates the result. Push to apply. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| actions | Yes | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| priority | No | ||
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No | ||
| triggerKind | No | System trigger instead of phrases | |
| triggerPhrases | No | User phrases that start the topic (OnRecognizedIntent) |
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 two-phase preview/confirm behavior, that the first call writes nothing, that it returns a diff, and that it validates the result. It omits permission/auth requirements and the semantics of the overwrite flag, which holds it back from a 5.
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 what gets created, followed by the node taxonomy and the confirm workflow. Dense but efficient; the fragment 'Validates the result. Push to apply.' is slightly cryptic and could be tightened.
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 9-parameter tool with a large nested action schema and no output schema, the description covers the essential create/validate/preview/confirm loop and the node vocabulary. It leaves overwrite and priority semantics unaddressed, but nothing critical to invoking it correctly 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?
At 44% schema coverage the description must compensate, and it partially does by explaining trigger phrases vs. system trigger and enumerating the action node kinds (message/question/condition/redirect/etc.). However priority, overwrite, workspace, and description are unexplained in both places, so the gap is only partly closed — 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?
States a specific verb (Create) and the exact resource it produces (topics/<name>.topic.mcs.yml), then enumerates the node kinds it accepts. This cleanly separates it from cs_edit_topic and other cs_add_* siblings without the agent needing to open a schema.
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?
Gives a strong operational flow: first call previews a diff, second call with confirm:true writes. What it lacks is explicit routing — it never names cs_edit_topic as the alternative for modifying an existing topic, so the agent must infer when-not-to-use from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create trigger/.trigger.mcs.yml pointing at a cloud flow that starts the agent (WorkflowExternalTrigger). The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| flowId | Yes | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key non-obvious behavior: the first call is a no-op that returns a diff for approval, and nothing is written without confirm: true. It omits overwrite semantics, error/permission behavior, and what the second call returns, keeping it below a 5.
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 tight sentences, front-loaded with what gets created before explaining the preview/confirm protocol. No wasted filler. Slightly dense but every clause contributes.
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?
No output schema and no annotations, so the description must cover behavior and returns. It correctly explains the first-call preview return (the diff) and the approval workflow, but does not describe the second-call result, failure modes, or overwrite interaction.
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 only 33% (only confirm and workspace are documented), so the description must compensate. It adds real meaning for confirm (gates the write) and implies name is used to build the file path, but flowId, overwrite, and description get no explanation in either place. Partial compensation merits a 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?
States a specific verb (Create) plus the exact artifact produced (trigger/<name>.trigger.mcs.yml) and the semantic role of that artifact (points at a cloud flow that starts the agent via WorkflowExternalTrigger). An agent can distinguish this from flow/topic/tool creation siblings without opening the schema.
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 describes the two-step flow: first call previews, second call with the same arguments plus confirm: true writes. This tells the agent when to call it and when to call it again. It doesn't name a sibling alternative or state prerequisites (e.g., flow must already exist), so it falls short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create variables/.variable.mcs.yml (GlobalVariableComponent, conversation scope). The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| overwrite | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No | ||
| aiVisibility | No | ||
| defaultValue | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the first call mutates nothing, returns a diff against current state, and requires an explicit confirm to commit. It omits behavior around overwrite (what happens to an existing variable), error conditions, and auth requirements, so it is strong but not exhaustive.
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 dense sentences that front-load the artifact created and immediately explain the two-phase confirm mechanic. No filler, though the preview/confirm detail is partially repeated by the schema's confirm description.
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 no annotations and no output schema, the description covers the critical safety mechanism (preview-then-confirm) but leaves the majority of parameters and the overwrite semantics unexplained. Adequate for the happy path, incomplete for full correct invocation.
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 29%, so the description is expected to compensate for undocumented parameters. It only reinforces 'confirm' (which the schema already documents) and says nothing about name, overwrite, description, aiVisibility, or defaultValue, leaving most parameters without meaning beyond their names.
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 (Create) and resource (global variable) and goes further by naming the exact artifact produced (variables/<name>.variable.mcs.yml, GlobalVariableComponent, conversation scope). This is unambiguous and clearly distinct from sibling 'add_*' tools like cs_add_topic, cs_add_tool, or cs_add_flow.
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 concrete procedural guidance: the first call is a preview, and you must call again with the same arguments plus confirm:true to actually write. That is clear when/how-to-use context. It does not name alternatives or state exclusions (e.g., when to use this vs. editing an existing variable), which keeps it below 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put an environment into an environment group, which applies that group's rules to it. Changes tenant configuration: requires confirm: true. Runs 'pac admin add-group' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id, url, unique or partial name | |
| timeoutSeconds | No | Default 600 | |
| environmentGroup | Yes | Environment group name or id |
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 that this mutates tenant configuration, that it is a live mutation requiring confirm: true, that omitting confirm yields a dry run, and that it shells out via 'pac admin add-group' under the active auth profile. It stops short of 5 only because it doesn't cover outcomes such as what happens if the environment is already in the group.
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?
It is short and front-loads the purpose, but it wastes space by stating 'requires confirm: true' twice in nearly identical form ('Changes tenant configuration: requires confirm: true' and 'Mutates a live environment: requires confirm: true'), which reads as padding rather than emphasis.
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 7-parameter, mutation-oriented tool with no annotations and no output schema, the description covers the essential agent-facing concerns: mutation, confirm/dry-run behavior, and the underlying pac invocation. Minor gaps remain around idempotency and the background job path described in the schema, but nothing critical 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 schema already documents all seven parameters including confirm, profile and background; the baseline here is 3. The description restates confirm semantics already in the schema without adding new parameter meaning (e.g. group name vs id resolution).
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 first sentence states a specific verb and resource ('Put an environment into an environment group') and adds the consequence ('applies that group's rules to it'), which is more than a restatement of the name. It does not, however, name any sibling (e.g. cs_admin_list_environment_groups) to distinguish membership assignment from group listing, so it stops 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 does convey the key precondition (requires confirm: true, otherwise a dry run), which is genuine usage guidance. But it never states when to reach for this tool versus alternatives like cs_admin_create_environment or cs_admin_list_environment_groups, so the routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give an Entra group a security role in an environment through a Dataverse team. Changes a live environment: requires confirm: true. Runs 'pac admin assign-group' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| role | Yes | Security role name or id | |
| group | Yes | Entra group object id | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| teamType | Yes | Team type (Owner, Access, AadSecurityGroup, AadOfficeGroup) | |
| groupName | Yes | Name of the Dataverse team to create | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| businessUnit | No | Business unit id | |
| membershipType | Yes | Membership type (MembersAndGuests, Members, Owners, Guests) | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key behavioral traits: it mutates a live environment, it is gated by confirm: true, it falls back to a dry run, and it runs 'pac admin assign-group' under the active pac auth profile. It stops short of stating required permissions or what happens on partial failure.
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 definition is short but wastes a sentence: 'Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise)' convey the same fact twice. The opening purpose sentence is well front-loaded, but the duplication means not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutation tool with no annotations and no output schema, the description covers the critical safety gate and execution mechanism, and the schema documents the remaining parameters fully. It omits what the dry run returns and how the background/timeout options interact, leaving a modest gap.
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 12 parameters including confirm, group, role, and teamType. The description only restates the confirm gate and references group/role/team generically, adding no syntax or format meaning beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: granting an Entra group a security role in an environment via a Dataverse team. That mechanism ('through a Dataverse team') distinguishes it from the sibling cs_admin_assign_user and from cs_admin_add_environment_to_group without requiring the agent to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides one important precondition (confirm: true is required to effect change, otherwise a dry run), which is genuine usage guidance. However, it never states when to choose this over cs_admin_assign_user, nor which environments/roles are valid targets, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give a user (or an application user) a security role in an environment. Changes a live environment: requires confirm: true. Runs 'pac admin assign-user' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| role | Yes | Security role name or id (cs_admin_list_security_roles) | |
| user | Yes | Object id or UPN, or the application id for an application user | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| businessUnit | No | Business unit id | |
| timeoutSeconds | No | Default 600 | |
| applicationUser | No | The user is an application (service principal) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key trait: it mutates a live environment and is gated by confirm:true with a dry run otherwise. But the confirm/dry-run fact is already spelled out in the schema's confirm parameter description, and the description adds no auth/permission, idempotency, or failure behavior beyond naming the underlying 'pac admin assign-user' command and auth profile.
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 says essentially the same thing twice: 'Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise).' That duplication wastes a large share of an otherwise short description and buries the one novel detail (the pac command/profile) in the middle.
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 10-parameter mutation tool with no annotations and no output schema, the description covers purpose, mutation nature, and the dry-run gate, which is the minimum viable set. It omits what the tool returns, how errors (e.g., unknown role) surface, and how it relates to the plural sibling, so 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?
Schema description coverage is 100%, so all ten parameters are already documented in the schema (user, role, environment, applicationUser, businessUnit, profile, confirm, etc.). The description adds no syntax, format, or default detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: giving a user (or application user) a security role in an environment, which maps cleanly onto the required user/role/environment parameters. However, it does not differentiate itself from the near-identical sibling cs_admin_assign_users (plural), which an agent would have to disambiguate on its own.
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 and no mention of alternatives, despite a confusingly similar sibling (cs_admin_assign_users) and related tools like cs_admin_list_security_roles and cs_admin_assign_group. The confirm requirement is stated, but that is a precondition, not usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give many users their security roles in one environment, from a CSV roster or an inline list. pac assigns one user and one role per call, so a roster of ten developers with three roles each is thirty calls; this expands the roster and runs them under a single approval. Without confirm it returns the plan: every user-and-role pair it would attempt, so you can read the whole thing before any of it happens. Rows are independent, so a bad UPN or a role the environment does not have is reported and the rest still run. Changes a live environment: requires confirm: true. Runs as the admin account: pass 'profile' or set CPS_ADMIN_PROFILE. Prefer cs_admin_assign_group when the roster is really a group: that is one call per role however many people are in it, and new joiners inherit access. Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| csv | No | Path to a CSV roster. Header row needs a user column (user, upn, email) and a roles column (roles, role); several roles in one cell separated by comma, semicolon or pipe. Optional businessUnit and applicationUser columns. A user on several rows accumulates their roles. | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile of the admin account; default CPS_ADMIN_PROFILE, then the active profile | |
| background | No | Run in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled. | |
| assignments | No | Roster inline instead of a CSV file | |
| environment | Yes | Environment id or URL to assign the roles in | |
| businessUnit | No | Business unit for rows that do not name one | |
| continueOnError | No | Default true: one failed row does not abort the roster. false stops at the first failure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so well: it discloses the dry-run behavior without confirm, the mutation/live-environment impact, the admin-account requirement (profile/CPS_ADMIN_PROFILE), per-row independence with partial failure semantics, the call-explosion cost model, and an honesty caveat ('Unverified against a live tenant'). This is unusually rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then cost model, dry-run safety, and the alternative. Dense but nearly every sentence earns its place; it runs slightly long, with the admin-account and unverified notes stacked near the end rather than in priority order.
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 being an 8-param mutation tool with no annotations and no output schema, the description covers safety, auth, partial-failure semantics, cost, and the return shape of the dry run. Nothing critical to calling it correctly 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 is 3, but the description adds meaning beyond the schema by explaining confirm as the live-vs-dry-run switch and the profile defaulting. It also contextualizes the roster expansion, though much parameter detail (CSV column syntax, background behavior) is already 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?
States a specific verb+resource+scope ('Give many users their security roles in one environment, from a CSV roster or an inline list') and immediately distinguishes itself from the single-assignment path ('pac assigns one user and one role per call') and from cs_admin_assign_group. An agent can identify the tool's job without opening the schema.
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 names when to use the alternative: 'Prefer cs_admin_assign_group when the roster is really a group.' It also gives the operating condition (requires confirm:true to change a live environment) so the agent knows when to set the flag. When-to-use, when-not, and the alternative are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a manual backup of an environment (the platform's own backup, not the file backup cs_backup_tenant writes). Changes a live environment: requires confirm: true. Runs 'pac admin backup' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| label | Yes | Backup label | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 3600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and mostly does: it discloses that this mutates a live environment, that confirm:true is required, and that otherwise a dry run is returned. It never mentions what happens to existing backups or retention, and the confirm/dry-run point is stated twice, slightly muddying the signal.
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 opening sentence is well front-loaded and useful, but the trailing sentence ('Changes a live environment: requires confirm: true... Mutates a live environment: requires confirm: true (a dry run otherwise).') restates the same fact twice and pads length without adding 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 7-parameter mutation tool with no annotations and no output schema, the description covers the key risk (live mutation, confirm gate, dry-run fallback) and the underlying command. It leaves backup retention/overwrite behavior and what the dry run returns unstated, which is a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter including confirm, profile, background, and timeoutSeconds is already documented in the schema. The description adds only the profile default behavior, which the schema also covers, so it does not meaningfully extend parameter meaning.
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 ('Take a manual backup of an environment') and explicitly distinguishes itself from the sibling cs_backup_tenant, which writes a file backup. An agent can pick this tool over that one without opening either schema.
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 clarifies the alternative (cs_backup_tenant's file backup vs this platform backup) and notes it runs with the active pac auth profile. It doesn't state when NOT to use it beyond that contrast, nor mention prerequisites like the confirm flag routing to cs_admin_list_backups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy a source environment onto a target environment. Everything in the target is replaced: requires confirm: true. Runs 'pac admin copy' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Name for the target environment | |
| type | No | Copy type (for example MinimalCopy, FullCopy) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| skipAuditData | No | Do not copy audit data | |
| timeoutSeconds | No | Default 14400 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) | |
| sourceEnvironment | No | Environment to copy from | |
| targetEnvironment | No | Environment to overwrite |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the target is fully replaced (destructive), that confirm:true gates the live mutation, and that omitting it yields a dry run. It also names the underlying command and auth profile, though it omits permission requirements and 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 destructive warning is front-loaded, which is good, but 'requires confirm: true' is stated twice in near-identical clauses, which is redundant. The 'active pac auth profile' phrasing also oversimplifies the schema's profile default logic (CPS_ADMIN_PROFILE vs CPS_PAC_PROFILE).
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-param destructive tool with no annotations or output schema, the description covers the critical behavior (overwrite, confirm gating, dry run). It could note that source/target environments are effectively required even though the schema lists zero required params, but otherwise the agent has enough to act safely.
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 12 parameters, including sourceEnvironment/targetEnvironment and confirm. The description restates confirm's semantics but adds no format or syntax detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Copy a source environment onto a target environment') and clarifies the overwrite semantics ('Everything in the target is replaced'). This distinguishes it well from create/backup siblings, though it never names a specific alternative like cs_admin_restore_environment or cs_clone_solution to route the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the confirm prerequisite and dry-run fallback, but gives no when-to-use vs alternatives guidance despite many adjacent admin tools (cs_admin_restore_environment, cs_admin_create_environment, cs_compare_environments). No exclusions or routing context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Dataverse environment in the tenant. Consumes tenant capacity: requires confirm: true. Runs 'pac admin create' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Environment name | |
| type | Yes | Production, Sandbox, Trial, Developer or Teams | |
| user | No | User to assign to the environment (object id or UPN) | |
| async | No | Run the operation asynchronously | |
| domain | No | Domain part of the environment URL | |
| region | No | Region (default unitedstates) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| currency | No | Currency (default USD) | |
| language | No | Language (default English) | |
| inputFile | No | JSON file with the arguments | |
| templates | No | Dynamics 365 templates to deploy | |
| appVersion | No | (Preview) Pin the application build, e.g. 10.0.43; Finance & Operations and Project Operations templates only | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| macroRegion | No | Macro-region id instead of a region, for tenants with Advanced Data Residency (pac 2.12) | |
| enableDemoData | No | (Preview) Install demo data; Finance & Operations and Project Operations templates only | |
| enableDevTools | No | (Preview) X++ developer tooling; Finance & Operations and Project Operations templates only, ignored otherwise | |
| timeoutSeconds | No | Default 7200 | |
| platformVersion | No | (Preview) Pin the platform build, e.g. 7.0.7256; needs appVersion | |
| securityGroupId | No | Entra security group id (required for a Teams environment) | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) | |
| enableTestModules | No | (Preview) Install the F&O test modules; Finance & Operations and Project Operations templates only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does a good job: it discloses that the operation mutates a live environment, defaults to a dry run without confirm, consumes tenant capacity, and runs 'pac admin create' under the active pac auth profile. It stops short of a 5 because it does not state required admin permissions or other tenant-level prerequisites beyond capacity.
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 purpose. It loses a point for redundancy: the phrase 'requires confirm: true' appears twice, once with capacity and once with live mutation, which could have been consolidated.
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 admin mutation with 23 parameters and no output schema, the description covers the essential agent-facing context: what it creates, that it is live and destructive with a dry-run default, that it consumes capacity, and what underlying command it runs. The schema covers the parameter details, and no return value explanation is needed, though the description could be slightly more complete by noting admin authorization requirements.
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% across 23 parameters, so the schema already carries the parameter semantics. The description mentions confirm and the active pac auth profile, but this largely repeats what the schema's confirm and profile descriptions already state, adding no new syntax or meaning.
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: create a Dataverse environment in the tenant. It is clearly distinct from list/delete/copy/reset siblings by verb, but it does not explicitly name or differentiate against the nearest alternative, cs_admin_copy_environment, so it falls short of a full 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 (create a tenant environment) and supplies two important preconditions: it consumes tenant capacity and requires confirm: true, otherwise returning a dry run. However, it gives no explicit when-not-to-use guidance and does not route the agent to alternatives such as cs_admin_copy_environment or cs_admin_list_environments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an Entra application and give it an application user with a security role in an environment: the headless identity a pipeline signs in as. Changes a live environment: requires confirm: true. Runs 'pac admin create-service-principal' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Application name to create in Entra | |
| role | No | Security role (default System Administrator) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does disclose key behavior: it mutates a live environment, requires confirm:true, otherwise performs a dry run, and runs the underlying 'pac admin create-service-principal' with the active auth profile. It omits permissions required and whether the operation is reversible, but the confirm/dry-run/mutation disclosure is substantive.
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?
It is front-loaded with the core purpose, but the confirm requirement is stated twice in near-identical form ('Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise)'). This redundancy wastes space and the dry-run fact also duplicates the confirm parameter's schema description.
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 no annotations and no output schema, the description covers mutation, confirm gating, dry-run behavior, and the underlying command. It does not indicate what the tool returns (e.g., application id, client secret), which an agent invoking a create tool would benefit from knowing given the absence of an output 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?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description reinforces the security-role and confirm-gating concepts, but adds little syntax or format detail 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 gives a specific verb and resource: 'Register an Entra application and give it an application user with a security role in an environment,' and adds the purpose ('the headless identity a pipeline signs in as'). This distinguishes it in spirit from cs_admin_register_application, but it never names that sibling explicitly, so the differentiation is inferential rather than stated.
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 'headless identity a pipeline signs in as' framing implies the use case (pipeline/service authentication), which is useful context. However, there is no explicit when-to-use vs alternatives guidance and no mention of the closely related cs_admin_register_application or cs_admin_list_service_principals, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an environment from the tenant, with everything in it: agents, solutions, flows and data. Irreversible beyond the platform's own backup retention: requires confirm: true. Runs 'pac admin delete' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 7200 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses irreversibility 'beyond the platform's own backup retention', the destructive scope of deleted assets, the confirm-gating and dry-run fallback, and the auth profile used. It omits finer operational detail such as timeout/background behavior and what the response contains, keeping it just under a 5.
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 destructive scope and irreversibility are front-loaded and every clause is relevant. It loses a point for redundancy: 'requires confirm: true' is asserted in one sentence and then restated in the closing sentence as 'Mutates a live environment: requires confirm: true (a dry run otherwise)'.
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 no-annotation, no-output-schema destructive tool with fully documented parameters, the description supplies the key safety context an agent needs: irreversibility, confirm gating, dry-run default, and the underlying command/auth. Only the return-shape and long-running (async/background) semantics are left to the schema, which is acceptable.
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 8 documented parameters, so the schema already does the heavy lifting and 3 is the baseline. The description reinforces the confirm semantics but adds little beyond the schema, and its 'active pac auth profile' phrasing slightly undersells the profile parameter's documented CPS_ADMIN_PROFILE default.
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 (delete an environment) plus the full blast radius — 'with everything in it: agents, solutions, flows and data'. This scope distinguishes it from adjacent siblings such as cs_admin_reset_environment, cs_admin_copy_environment and cs_delete_solution without the reader needing to open those schemas.
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?
Gives the operative condition clearly: confirm: true performs the deletion, otherwise the tool returns a dry run, and it names the underlying 'pac admin delete' command with the active auth profile. It does not, however, explicitly route the agent between this and alternatives like reset or restore, so it stops short of a full when/when-not/alternative statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of the tenant operations that are still running (copies, restores, resets, deletions). Runs 'pac admin status' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the mechanism ('Runs pac admin status') and that it uses the active pac auth profile, which signals a read-only CLI query, but it never explicitly states read-only/non-destructive behavior, permission requirements, or what the status output contains.
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-loaded with the resource and its scope, followed by the implementation note. No filler, though the 'pac admin status' sentence is slightly more internal detail than an agent strictly needs.
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?
No output schema exists, so the description should ideally characterize the returned status (fields, format, how to interpret 'still running'). It stops at naming the operation types, leaving the shape of the response unspecified for a tool whose entire purpose is reporting status.
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 cwd, profile, background, and timeoutSeconds in detail. The description adds only a passing reference to the 'active pac auth profile', which relates to the profile param but adds no real semantics 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?
States a specific resource and scope: 'Status of the tenant operations that are still running', with the concrete operation types (copies, restores, resets, deletions) named. This distinguishes it from the generic cs_status and from cs_job_status, though it never explicitly contrasts with those 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?
Usage is only implied: the reader infers this is the tool to check for in-flight tenant operations. The only routing help is buried in the background param description ('Poll cs_job_status'), and there is no explicit statement of when to use this versus cs_job_status or cs_list_org_agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Entra applications registered with the tenant for Power Platform. Runs 'pac admin application list' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
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 underlying command ('pac admin application list') and the execution context (active pac auth profile), which implies a read-only listing operation, but it says nothing about returned fields, pagination/volume, or required admin permissions.
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 short sentences with the purpose front-loaded and the implementation detail second. Nothing is wasted, though the content is sparse enough that it borders on under-specification rather than tightness.
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 no-argument list tool with full schema coverage and no output schema, the essentials are covered. However, in a sibling cluster containing list_service_principals and list_app_templates, the absence of any disambiguation leaves the agent to guess which lister fits the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (cwd, profile, background, timeoutSeconds) are already documented. The description's mention of the active auth profile aligns with the profile parameter but adds no syntax or meaning beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (Entra applications registered with the tenant for Power Platform), so an agent knows this is a listing operation over tenant-registered apps. It does not explicitly differentiate from near siblings like cs_admin_list_service_principals or cs_admin_list_app_templates, but the resource is distinct enough to be actionable.
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 when-to-use guidance, no prerequisites, and no named alternative. The agent must infer that this is the right tool when it wants registered applications rather than service principals or app templates, all of which are separate sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Dynamics 365 application templates that can be installed when creating an environment, per region. Runs 'pac admin list-app-templates' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| region | No | Region name (default unitedstates) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the backing command ('pac admin list-app-templates') and that it runs under the active pac auth profile, which is real context. However it never states that the call is read-only/side-effect free, nor anything about result volume or pagination, leaving gaps for a no-annotation 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?
Two sentences, zero filler, with the resource definition front-loaded and the execution detail second. It is appropriately sized for a simple list command, though the second clause overlaps with what the profile parameter already explains.
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 no-annotation, no-output-schema listing tool with five all-optional parameters, the description covers what the tool surfaces and how it runs, which is adequate. It does not indicate that no parameters are required or describe the shape of the returned template list, so an agent cannot fully predict the response.
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 optional parameters (cwd, region, profile, background, timeoutSeconds) are already documented in the schema. The description only echoes 'per region', adding no syntax, defaults, or interplay beyond what the schema provides; baseline 3 is correct.
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?
Identifies the resource precisely (Dynamics 365 application templates available for environment creation, scoped per region). The title supplies the 'List' verb and the description makes the scope concrete. It does not explicitly differentiate itself from the nearby sibling cs_admin_list_applications, so it stops 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?
Usage is only implied via 'templates that can be installed when creating an environment', which hints the agent should call this before cs_admin_create_environment. There is no explicit when-to-use, when-not-to-use, or named alternative, so it lands at the minimum-viable level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Backups of an environment, with their labels and dates: what cs_admin_restore_environment can restore. Runs 'pac admin list-backups' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It usefully reveals the underlying command ('pac admin list-backups') and the auth context (active pac auth profile), which implies a read-only operation, but it never confirms read-only semantics, side effects, or auth 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?
Two compact sentences with no filler, front-loading what the tool returns and then the restore relationship and execution mechanism. Every clause carries 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 full schema coverage and no output schema, the description is nearly sufficient: it explains what comes back (labels and dates) and how it runs. Only ordering, volume/pagination, and empty-result behavior are left unspecified.
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 5 parameters, so the schema already documents cwd, profile, background, environment, and timeoutSeconds. The description only gestures at the environment parameter ('backups of an environment') and adds no syntax, default, or format detail 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 names a specific resource (backups of an environment) and its content (labels and dates), which is enough to distinguish it from siblings like cs_admin_backup_environment or cs_backup_tenant. The verb is only implied via the tool name, but the resource and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes context by tying the output to what cs_admin_restore_environment can restore, implying 'list before you restore', but never states that intent explicitly and offers no exclusions or alternatives. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Data loss prevention policies in the tenant: the connector groups that decide which connectors an agent or flow may combine. Runs 'pac admin dlp-policy list' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
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 mechanism ('pac admin dlp-policy list' with the active pac auth profile), which hints at auth prerequisites, but it never states that the operation is read-only, nor anything about output size, pagination, or error behavior of a list command.
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 resource and then the domain explanation; very little waste. The trailing pac-command detail is arguably internal mechanics rather than agent-facing information, which keeps it just short of a 5.
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 low-complexity list command with four optional parameters fully documented in the schema and no output schema, the description supplies useful domain context about what DLP policies represent. It still omits the read-only nature and any sense of what the listing returns, so it is adequate rather than 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 schema already documents cwd, profile, background, and timeoutSeconds in detail. The description's only parameter-adjacent remark is the 'active pac auth profile' usage, which the profile parameter description covers more thoroughly. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource precisely (tenant DLP policies) and even explains what a DLP policy is functionally (connector groups that govern which connectors an agent or flow may combine). It lacks an explicit verb phrase and does not distinguish itself from the sibling cs_admin_show_dlp_policy, 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?
There is no when-to-use guidance and no routing to alternatives, even though cs_admin_show_dlp_policy sits right next to it in the sibling list. The mention of the underlying pac command is implementation detail, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Environment groups in the tenant (the grouping used for managed-environment rules). Runs 'pac admin list-groups' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose that it runs 'pac admin list-groups' against the active pac auth profile, which tells the agent the operation is tenant-scoped and auth-dependent. It stops short of saying anything about return contents, pagination, or the read-only nature of the call.
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 compact sentences with the resource definition front-loaded and the implementation detail second. 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 simple read-only list command with no output schema and no annotations, the definition covers the basics but leaves the agent guessing about what the listing returns (names, IDs, rule associations) and how to interpret results. 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?
Schema description coverage is 100%, so all four parameters (cwd, profile, background, timeoutSeconds) are already documented in the schema. The description adds no parameter-level detail beyond implicitly referencing the active auth profile; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (environment groups in the tenant) and clarifies what they are ('the grouping used for managed-environment rules'), which is more than a bare restatement of the title. The listing verb is implied rather than stated, and it does not distinguish itself from the related sibling cs_admin_add_environment_to_group, but the intent is 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?
There is no statement of when to use this tool, no prerequisites, and no reference to an alternative such as cs_admin_list_environments or the group-modification sibling. The mention of the pac auth profile hints at an auth requirement but is not framed as usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every environment in the tenant with its type, region and state, as the admin centre lists them. Filters by name, type or installed application. Runs 'pac admin list' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Only environments whose name contains this text | |
| type | No | Only environments of this type (Production, Sandbox, Trial, Developer, Teams) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| application | No | Only environments with this application installed | |
| environment | No | Only environments whose name or id contains this text | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the execution mechanism ('pac admin list' with the active pac auth profile), which implies a safe read. However, it does not state read-only intent explicitly, nor address permissions, pagination, or failure modes, leaving meaningful behavioral gaps for an unannotated 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?
Three short sentences, front-loaded with what is returned, then filters, then the underlying command. No filler. Slightly less tight than ideal because the command detail is tacked on, but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description is adequate: it names the returned fields and the filters. It does not describe the return shape beyond those three fields, nor how results are ordered or paged, and gives no guidance against the adjacent environment-listing tools.
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 8 parameters, including profile defaults and background/polling behavior. The description only restates the filter set (name, type, installed application) and the profile usage, adding no syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Every environment in the tenant') and enumerates the returned fields (type, region, state), plus notes it mirrors the admin centre listing and runs 'pac admin list'. This clearly separates it from non-admin listing siblings. It never names the closest sibling (cs_list_environments or cs_admin_environment_status), 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?
Usage is only implied: 'as the admin centre lists them' and the note about the admin auth profile suggest the admin scope, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. cs_list_environments for non-admin listing). The agent must infer the routing from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Security roles in an environment, optionally including child roles: what cs_admin_assign_user and cs_admin_assign_group can grant. Runs 'pac admin list-roles' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| businessUnit | No | Filter by business unit name or id | |
| timeoutSeconds | No | Default 600 | |
| includeChildRoles | No | Include child roles |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose the underlying command ('pac admin list-roles') and that it runs under the active pac auth profile, which hints at both read-only behavior and authorization context. However, it never explicitly states the operation is non-destructive, nor does it describe the shape or volume of the returned roles.
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?
A single compact clause packs the resource, the optional scope, the downstream consumer, and the execution mechanism with no filler. It is front-loaded, though the key verb is omitted and the second sentence is implementation detail.
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 7-parameter, zero-required tool with no output schema, the description should say what a returned role looks like and which parameters (environment, profile) are effectively needed. It explains only the child-role option and the CLI invocation, leaving the return contract unstated.
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% (all 7 params documented, including includeChildRoles as 'Include child roles'), so the schema does the heavy lifting. The description's mention of 'optionally including child roles' largely restates the schema rather than adding format or cost nuance.
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 resource ('Security roles in an environment') and the optional scope ('optionally including child roles'), and ties it to a concrete downstream use ('what cs_admin_assign_user and cs_admin_assign_group can grant'), which separates it from the assign siblings. The verb is only implicit (title supplies 'List'), so it falls just short of the 5 bar.
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?
Usage is only implied: an agent can infer this is the discovery step before cs_admin_assign_user or cs_admin_assign_group. There is no explicit when-to-use statement, no when-not-to-use, and no exclusion of an alternative listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Entra applications that have an application user in Dataverse: who can act without a person signing in. Runs 'pac admin list-service-principal' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| max | No | Maximum applications (default 20) | |
| filter | No | Application name starts-with filter | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
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 the underlying command ('pac admin list-service-principal') and that it runs against the active pac auth profile, which hints at a read operation and its auth dependency. However, it says nothing about result volume, pagination, or the effect of the max/filter parameters on 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?
Two tight sentences: the first defines the resource, the second anchors the underlying command and auth context. Front-loaded and waste-free, with only mild redundancy around the auth profile.
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 no output schema and no annotations, the description explains what the tool conceptually returns but omits any sense of output shape or pagination behavior. For a six-parameter list tool, it is adequate but not fully self-sufficient.
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 six parameters are already documented in the schema. The description only echoes the auth-profile behavior ('with the active pac auth profile'), adding no meaningful semantics beyond what the schema's 'profile' description 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 states a specific resource (Entra applications with an application user in Dataverse) and clarifies the concept (apps that act without a person signing in), plus the underlying command. It is clear what the tool lists, though it does not explicitly differentiate itself from siblings like cs_admin_list_applications or cs_admin_create_service_principal beyond the verb 'list'.
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 use this tool versus alternatives such as cs_admin_list_applications (Entra app registrations) or cs_admin_register_application. Usage is only implied by the resource name; no preconditions or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tenant-wide Power Platform settings (governance, sharing, support, licensing). With settingsFile, pac writes them as JSON to that path; that file is the reference copy to keep in source control. Runs 'pac admin list-tenant-settings' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| settingsFile | No | Write the settings to this .json file | |
| timeoutSeconds | No | Default 600 |
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 the side effect of writing JSON to settingsFile, the source-control purpose of that file, and that it runs with the active pac auth profile — useful behavioral context. It does not state read-only/non-destructive guarantees explicitly (implied by 'list') or permission 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?
Three tightly packed sentences, front-loaded with the resource and scope, then the settingsFile behavior, then the underlying command. No filler; every sentence contributes.
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 tool with no annotations and no output schema, the description covers purpose and the file-output path well. It does not explain what is returned when settingsFile is omitted, which is the remaining gap given the absence of an output 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?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for settingsFile by explaining that pac writes JSON there and that the file is the reference copy for source control — more than the schema's terse 'Write the settings to this .json file'.
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/resource ('tenant-wide Power Platform settings') and enumerates the covered categories (governance, sharing, support, licensing), plus names the underlying command 'pac admin list-tenant-settings'. An agent can distinguish this read tool from the write counterpart cs_admin_update_tenant_settings.
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?
Implies usage through the settingsFile note (keep the file in source control), which gives context for a common workflow, but never states when to use this vs. cs_admin_update_tenant_settings or other admin listing tools. Usage is inferred rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a tenant-level resource query (the admin centre's own query language) and optionally write the results to a file as JSON, list or CSV. Runs 'pac admin query' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| query | No | Resource query JSON as a string | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| queryFile | No | File containing the query JSON | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| outputFile | No | Where to save the results | |
| outputType | No | Json, List or Grid (default Grid) | |
| timeoutSeconds | No | Default 600 |
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 underlying command and that results can be written to a file, but never says whether a resource query can mutate tenant state, what permissions the profile needs, or how background jobs behave beyond the schema's own text. For an unannotated tool that shells out to a CLI, that is a meaningful 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?
Two tight sentences with no filler, and the core action is front-loaded ahead of the output-file clause. Efficient, though the second sentence's CSV/Grid slip costs it a point.
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 8 optional parameters, no annotations and no output schema, the description does enough to identify the operation but not enough to call it safely: no read/write semantics, no guidance on query vs queryFile, and a wrong outputType value. The schema's per-parameter text covers the defaults, which keeps this at a minimum-viable 3.
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 would be 3, but the description actively misleads on outputType: it says 'JSON, list or CSV' while the enum only allows Json, List, Grid. An agent following the prose could pass 'CSV' and fail. The rest of the description adds nothing 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?
Clear verb+resource: 'Run a tenant-level resource query' plus the concrete mechanism ('pac admin query'), which distinguishes it from deterministic siblings like cs_admin_list_environments or cs_admin_list_tenant_settings. It doesn't explicitly say how it differs from those narrower list tools, but the generic query framing implies the distinction.
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 when-to-use guidance and no named alternatives, despite sitting among 90+ siblings with many overlapping admin-read tools. An agent is left to infer that this is the escape hatch when a dedicated cs_admin_* list tool doesn't cover the needed resource, and nothing states that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an Entra application with the tenant so it can be used by Power Platform. Changes tenant configuration: requires confirm: true. Runs 'pac admin application register' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| applicationId | Yes | Application (client) id | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this changes tenant configuration, that it mutates a live environment, and that omitting confirm produces a dry run. It does not say what permissions are needed beyond the admin profile or what happens on failure, which keeps it from a 5.
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 purpose in the first sentence, which is good. However, the confirm requirement is stated twice in slightly different words ('Changes tenant configuration: requires confirm: true' and 'Mutates a live environment: requires confirm: true'), which is wasted space in an otherwise short description.
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 tenant-mutating tool with no annotations and no output schema, it covers the critical operational facts: mutation, confirm gating, dry-run fallback, and the pac command it wraps. It leaves out permissions, error behavior and idempotency, so it is strong but not exhaustive.
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 six parameters are already documented, including confirm's dry-run behavior and profile's defaults. The description restates the confirm semantics rather than adding new parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Register an Entra application with the tenant') plus the downstream benefit ('so it can be used by Power Platform'). This is clearly distinct from the sibling cs_admin_unregister_application and from app-creation tools like cs_admin_create_service_principal.
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 by naming the underlying command and the confirm gate, so an agent knows it is a live tenant mutation, but it never states when to prefer this over alternatives (e.g., cs_admin_create_service_principal) or any exclusions. Prerequisite awareness is partial rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset an environment to an empty Dataverse instance. Everything in it is deleted: requires confirm: true. Runs 'pac admin reset' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | New name | |
| async | No | Run the operation asynchronously | |
| domain | No | Domain part of the URL | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| purpose | No | Description of the environment's intent | |
| currency | No | Currency | |
| language | No | Language | |
| inputFile | No | JSON file with the arguments | |
| templates | No | Dynamics 365 templates | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 7200 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares this is destructive ('Everything in it is deleted'), that it mutates a live environment, that confirm:true is required, and that omitting it yields a dry run. It still doesn't state irreversibility or whether a backup is taken first, which matters for a wipe 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?
Front-loaded with the key purpose and danger, but 'requires confirm: true' is stated twice in slightly different wording, which is wasted repetition in a four-sentence description.
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 tool with no annotations and no output schema, the description covers purpose, blast radius, the confirm gate and the auth profile dependency. The remaining gaps (irreversibility/backup, return shape) are minor but non-zero for an operation this consequential.
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% across 15 parameters, so the schema already documents every field. The description reinforces the gating semantics of confirm (dry run without it) but adds no syntax or value guidance for the other parameters beyond what the schema states, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Reset an environment to an empty Dataverse instance') and the consequence in the same breath, which cleanly separates it from siblings like cs_admin_delete_environment, cs_admin_copy_environment and cs_admin_restore_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?
Gives clear conditions: the operation mutates a live environment, requires confirm: true, and otherwise returns a dry run, plus the note that it runs under the active pac auth profile. It does not explicitly name alternatives (e.g. delete vs. restore) for an agent weighing options, 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.
Restore a backup into the same or another environment. Overwrites the target's data and customisations: requires confirm: true. Runs 'pac admin restore' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Name for the restored environment | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| skipAuditData | No | Do not restore audit data | |
| selectedBackup | Yes | Backup date as mm/dd/yyyy hh:mm, or 'latest' | |
| timeoutSeconds | No | Default 14400 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) | |
| sourceEnvironment | No | Environment the backup came from | |
| targetEnvironment | No | Environment to restore into (defaults to the source) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the target's data AND customisations are overwritten, that confirm: true is required to actually mutate, that omitting it yields a dry run, and that it runs under the active pac auth profile. It stops short of stating irreversibility, permission/elevation requirements, or expected duration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all front-loaded and on-topic, but the confirm requirement is stated twice in near-identical wording ('requires confirm: true' ... 'requires confirm: true (a dry run otherwise)'), which is redundant filler in an otherwise tight description.
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 destructive admin tool with no output schema and no annotations, the description covers the critical decision inputs: destination scope, overwrite semantics, confirm/dry-run gate, and the underlying command. Return-value behavior is left unexplained, though the schema's background/jobId parameter hints at async polling via cs_job_status.
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 12 parameters including selectedBackup format, sourceEnvironment/targetEnvironment, profile, background/jobId, and confirm are already documented in the schema. The description only restates the confirm behavior and adds no new parameter-level detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource (restore a backup into an environment) and states the scope (same or another environment), and the pac invocation ('pac admin restore') anchors exactly what is executed. It does not explicitly name or contrast with the nearest siblings (cs_admin_copy_environment, cs_admin_reset_environment, cs_admin_backup_environment), so an agent must infer the distinction from context.
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 tells the agent the primary gate (confirm: true, otherwise a dry run) and that the target must be an environment, which is useful. But it gives no explicit when-to-use/when-not guidance against the adjacent lifecycle tools like copy, reset, or snapshot, and no prerequisites beyond the confirm flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give yourself the System Administrator role in an environment. Needs Global, Power Platform or Dynamics 365 admin. Changes a live environment: requires confirm: true. Runs 'pac admin self-elevate' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the key traits: it mutates a live environment, requires explicit confirmation, returns a dry run without it, needs caller admin rights, and runs via the active pac auth profile. It stops short of stating irreversibility or downstream effects, but the mutation/confirmation/auth profile 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?
Mostly front-loaded and understandable, but it redundantly states the mutation/confirmation rule twice ('Changes a live environment: requires confirm: true' and again 'Mutates a live environment: requires confirm: true (a dry run otherwise)'). That duplication wastes space in an otherwise short description.
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 privileged mutation with no annotations and no output schema, it covers the essentials: prerequisite admin role, confirm requirement, dry-run fallback, underlying command, and auth-profile behavior. Missing only return-value and reversibility context, which is minor here.
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 cwd, confirm, profile, background, environment, and timeoutSeconds. The description reinforces the confirm semantics (dry run without it) but adds no format or value guidance beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (grant yourself the System Administrator role) on a specific resource in an environment, and names the underlying operation ('pac admin self-elevate'). It is clearly distinguishable from sibling cs_admin_* list/set tools, which deal with environments, settings, and policies rather than granting the caller admin.
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?
Gives a concrete prerequisite ('Needs Global, Power Platform or Dynamics 365 admin') and the gating condition for actually performing the change ('requires confirm: true', dry run otherwise). This is clear context for when it will and won't act, though it does not name alternate tools for elevation or post-elevation workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set how many days backups of an environment are kept (7, 14, 21 or 28). Changes a live environment: requires confirm: true. Runs 'pac admin set-backup-retention-period' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| days | Yes | 7, 14, 21 or 28 | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL | |
| timeoutSeconds | No | Default 600 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this mutates a live environment, that confirm: true is required to act, that without it the tool returns a dry run, and that it runs the underlying 'pac admin set-backup-retention-period' with the active auth profile. It stops short of stating required permissions or the shape/content of the result.
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?
It is short but redundant: the live-environment/confirm:true constraint is stated twice in near-identical sentences ('Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise)'). The allowed-values fact is front-loaded well, but the duplication wastes 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?
For a mutation command with no annotations and no output schema, the description covers the essentials an agent needs: what changes, that it is destructive/live, and the confirm gate. It could mention permissions or the result format, but it is close to complete for this operation.
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 nine parameters, making 3 the baseline. The description adds value by restating the valid 'days' values and the confirm gating semantics, but adds no syntax that is not already 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?
States a specific verb and resource ('Set how many days backups of an environment are kept') and even enumerates the allowed values 7/14/21/28. The purpose is unambiguous and clearly distinct from adjacent siblings like cs_admin_backup_environment or cs_admin_list_backups, though it never explicitly contrasts itself with 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?
It reveals a hard prerequisite (confirm: true) but gives no when-to-use guidance, no conditions for choosing this over alternatives, and no mention of related operations like restore or backup. The agent must infer the appropriate usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn managed environments on ('Standard') or off ('Basic') for an environment and set its governance options: sharing limits, solution checker mode, maker onboarding. Changes tenant governance: requires confirm: true. Runs 'pac admin set-governance-config' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | Yes | Environment id or URL | |
| cloudFlowsMode | No | Sharing limit mode for solution cloud flows | |
| timeoutSeconds | No | Default 600 | |
| cloudFlowsLimit | No | How many people makers may share solution cloud flows with | |
| excludeAnalysis | No | Exclude this environment from the weekly usage digest | |
| includeInsights | No | Show insights on the admin centre home page | |
| protectionLevel | Yes | Standard enables managed environments, Basic disables them | |
| limitSharingMode | No | Sharing limit mode | |
| makerOnboardingUrl | No | Maker onboarding URL | |
| disableGroupSharing | No | Disable sharing with groups | |
| maxLimitUserSharing | No | How many people makers may share canvas apps with | |
| solutionCheckerMode | No | Solution checker validation mode (None, Warn, Block) | |
| checkerRuleOverrides | No | Solution checker rule overrides | |
| makerOnboardingMarkdown | No | Maker onboarding markdown | |
| suppressValidationEmails | No | Do not send validation emails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that this mutates a live environment, that confirm: true is required, and that omitting it yields a dry run, plus which pac command runs. However it does not state what happens to unset governance options, whether changes are reversible, or what permissions the admin profile 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?
Core purpose is front-loaded and clear, but the description is redundant: 'requires confirm: true' is stated twice and the dry-run behavior is repeated. That duplicated warning costs space without adding 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 19-parameter tenant-governance mutation with no annotations and no output schema, the description covers purpose and the confirm gate adequately, and the schema handles parameters. It remains incomplete on sibling routing and on the effect of unspecified options, which matters for a broad mutation.
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 19 parameters; baseline is 3. The description adds only light mapping (protectionLevel Standard/Basic, and the categories of governance options), not syntax or interaction details 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 verb+resource: turn managed environments on ('Standard') or off ('Basic') and set governance options (sharing limits, solution checker mode, maker onboarding). This clearly distinguishes it from sibling admin tools like cs_admin_update_tenant_settings or cs_admin_set_runtime_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states preconditions (confirm: true, tenant-wide scope) but gives no when-to-use guidance relative to siblings, nor any exclusions or alternative tools for adjacent governance tasks. An agent must infer context on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put an environment into administration mode (only admins can use it) or back, and control background operations. Changes a live environment: requires confirm: true. Runs 'pac admin set-runtime-state' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | Yes | Environment id or URL | |
| runtimeState | Yes | AdminMode or Enabled | |
| timeoutSeconds | No | Default 600 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) | |
| backgroundOperations | No | Background operations state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It does well by disclosing that this mutates a live environment, that confirm: true is mandatory and the call otherwise returns a dry run, and that it runs 'pac admin set-runtime-state' under the active pac auth profile. It omits the blast radius (does enabling AdminMode kill in-flight background operations?) and reversibility details.
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 first sentence is well front-loaded, but the description repeats itself: 'Changes a live environment: requires confirm: true' and 'Mutates a live environment: requires confirm: true (a dry run otherwise)' say the same thing twice in different words. That redundancy costs space that could have documented backgroundOperations or async behavior.
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 10-parameter, no-output-schema, no-annotation mutation tool, the description covers the essential risk profile: live-environment mutation, mandatory confirm with dry-run fallback, and the auth context. Remaining gaps (effect on running operations, what backgroundOperations accepts, async/background interplay) are minor since the schema documents those parameters with full coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so a baseline of 3 applies and the description must add meaning on top. It does: runtimeState values are glossed ('administration mode (only admins can use it) or back'), and it clarifies confirm's dry-run behavior and the profile source. The backgroundOperations parameter is only vaguely gestured at ('control background operations'), which keeps this from a 5.
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+resource (put an environment into/out of administration mode) and states what that mode means ('only admins can use it'), plus the secondary control of background operations. It is distinguishable from the many cs_admin_* siblings, which handle users, backups, environments, and settings, not runtime state. It stops short of explicitly naming a sibling it is not, so it lands at 4 rather than 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 an important precondition ('requires confirm: true', otherwise a dry run) and frames the operation as acting on a live environment, which implies when it is appropriate. However, it never states when to use this vs. alternatives (e.g. cs_admin_reset_environment or cs_update_settings) or when to avoid it, e.g. while other admin operations are in flight. Guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One data loss prevention policy in full: its connector classification and the environments it applies to. Runs 'pac admin dlp-policy show' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| policyName | Yes | Policy id (GUID); cs_admin_list_dlp_policies shows it | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the underlying command ('pac admin dlp-policy show') and that it runs with the active pac auth profile, which is useful operational context, but it does not explicitly confirm read-only behavior, permissions, or side effects beyond what 'show' 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 tight sentences, front-loaded with what the tool returns and followed by the command used. Every sentence earns its place with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-style admin tool with fully documented parameters, the description explains the return contents ('connector classification and the environments it applies to') and the execution context. It is largely complete, though it could say more about the read-only nature and when to prefer this over the list sibling.
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 five parameters, including policyName. The description adds no additional parameter meaning, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: 'One data loss prevention policy in full: its connector classification and the environments it applies to.' This distinguishes it from the list sibling by emphasizing a single full policy, though it does not name cs_admin_list_dlp_policies as the alternative in the main description.
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 'One data loss prevention policy in full' implies this tool is for inspecting a single policy rather than enumerating policies, but there is no explicit when-to-use or when-not-to-use guidance versus cs_admin_list_dlp_policies. Usage is left to inference from the scope wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an Entra application's tenant registration. Changes tenant configuration: requires confirm: true. Runs 'pac admin application unregister' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| applicationId | Yes | Application (client) id | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose key behavior: it mutates a live environment, requires confirm: true, defaults to a dry run, and shells out via the active pac auth profile. It falls short of stating reversibility or permission requirements, but covers the mutation/safety profile well.
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 purpose is front-loaded and the writing is mostly economical, but 'requires confirm: true' is stated twice in nearly identical phrasing, which is redundant filler in an otherwise short description.
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 no annotations and no output schema, the description covers the essential behavioral context (dry-run default, live-environment mutation, profile selection). It could be stronger on consequences and reversibility, but nothing critical to correct invocation 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 all six parameters are documented in the schema itself, establishing the baseline of 3. The description echoes the confirm and profile behavior rather than adding new syntax or format meaning 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 verb and resource ('Remove an Entra application's tenant registration') and clearly contrasts with its sibling cs_admin_register_application. An agent can identify the operation without opening the schema.
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?
Usage context is implied through the confirm requirement and the dry-run note, but there is no explicit when/when-not guidance and no named alternative (e.g. re-registering via cs_admin_register_application). It is adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change tenant-wide settings, either from a settings file or one setting at a time (for example powerPlatform.governance.disableDeveloperEnvironmentCreationByNonAdminUsers). Affects the whole tenant: requires confirm: true. Runs 'pac admin update-tenant-settings' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| settingName | No | Single setting path | |
| settingValue | No | Value for that setting | |
| settingsFile | No | A .json file of settings (from cs_admin_list_tenant_settings) | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses tenant-wide blast radius, the confirm:true gate with dry-run fallback, and that it wraps 'pac admin update-tenant-settings' under the active auth profile. It does not describe failure/partial-apply behavior or the response shape, leaving some behavioral gaps.
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 and compact, with scope stated first. However, 'requires confirm: true' is repeated twice in consecutive sentences, wasting a sentence that could have carried additional 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 an 8-parameter mutation tool with full schema coverage and no output schema, the description covers scope, safety gating, the underlying command, and both invocation modes. Nothing critical to correct invocation 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 baseline is 3; the description adds value by framing settingName/settingValue as the per-setting mode versus settingsFile as the bulk mode, which the schema alone does not make explicit. It does not state whether the two modes are mutually exclusive or how settingsFile interacts with confirm.
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 (change) and resource (tenant-wide settings), and explicitly names both input modes (settings file vs individual setting), with a concrete example setting path. It is clearly distinguishable from the sibling read tool cs_admin_list_tenant_settings.
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 this to change tenant-wide settings, and it points to cs_admin_list_tenant_settings as the source of a settings .json file. It lacks explicit when-not guidance (e.g., prefer cs_admin_set_governance_config for governance-only changes) among many sibling admin tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How reliable a cloud flow is across its recent runs: failure rate, duration spread (median and 90th percentile), and which actions the failures concentrate on. The verdict distinguishes one broken step from failures spread across many actions, which points at a connection, throttling or an unreliable downstream system instead. Read-only. Use it before cs_explain_flow_run when the complaint is 'it fails sometimes' rather than 'it failed just now'. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| lastN | No | Runs to examine; default 50 | |
| flowId | Yes | Flow id (cs_list_flows) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| sampleFailures | No | Failed runs to open for action-level attribution; default 5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the safety burden and does so partially: it declares 'Read-only', names the required auth (Power Automate service, cs_login scope 'flow'), and flags 'Unverified against a live tenant'. It also explains what the verdict means diagnostically (one broken step vs. many actions pointing at a connection/throttling). It stops short of documenting throttling, rate limits, or cost of sampling many failed runs.
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 dense sentences, each earning its place: capability, interpretive meaning of the verdict, safety/auth note, and routing guidance. The core capability is front-loaded and nothing is padding.
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 outputs conceptually, the auth scope, and sibling routing, which is substantial for a diagnostic tool with no output schema. Minor gaps remain around the return shape and the cost/latency of scanning many runs, but an agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: lastN, sampleFailures, flowId, clientId, tenantId, workspace and environmentId all carry their own defaults and provenance in the schema. The description adds no syntax or semantics beyond what the schema already states, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (analyze/assess) and resource (a cloud flow's reliability) and enumerates the concrete outputs: failure rate, duration spread at median and 90th percentile, and action-level failure concentration. It is immediately distinguishable from siblings like cs_get_flow_run or cs_explain_flow_run, which deal with a single run.
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 routes the agent: 'Use it before cs_explain_flow_run when the complaint is "it fails sometimes" rather than "it failed just now".' It names the alternative tool and the condition that selects between them, so selection requires no inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who pac is signed in as, and against which environment. Runs 'pac auth who' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
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 underlying command ('pac auth who') and that it operates on the active pac auth profile, implying a safe read. It does not explicitly state the operation is read-only or describe any side effects, but for a benign identity query this is a modest 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?
Two short sentences with zero waste; the identity-and-environment answer is front-loaded before the implementation detail. 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?
A simple read-only query tool with no output schema and fully documented parameters, so little more is required. The one remaining gap is disambiguating from sibling identity/profile tools, which the description omits.
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 four parameters (cwd, profile, background, timeoutSeconds) are already fully documented, including profile-resolution logic. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource — it reports who pac is signed in as and the environment — which is clear and concrete. However, it does not differentiate itself from near-identical siblings such as cs_list_auth_profiles, cs_login_status, and cs_env_who, leaving the agent to infer the distinction.
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 when-to-use vs. when-not guidance and names no alternatives, despite several overlapping siblings (cs_login_status, cs_list_auth_profiles, cs_env_who) that could plausibly serve a similar purpose. The agent gets no signal for selecting this tool over those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write the tenant's Power Platform configuration to local files for reference, diffing and source control: tenant settings, environments, DLP policies, environment groups, service principals, registered applications and app templates, plus per environment its details, solutions, agents, connections, security roles and platform backups. Read-only for the tenant; it only writes files. Runs as the admin account: pass 'profile' or set CPS_ADMIN_PROFILE. Each capture is independent, so a command the account cannot run is reported in 'skipped' and the rest still completes.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Folder to write the backup into (created; existing files with the same names are overwritten) | |
| profile | No | pac auth profile of the admin account; default CPS_ADMIN_PROFILE, then the active profile | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| environments | No | Environments to detail; default: every environment 'pac admin list' returns | |
| includeRoles | No | Default true: the security roles of each environment | |
| includeBackups | No | Default true: the platform backups of each environment | |
| maxEnvironments | No | Default 50 | |
| includeDataverse | No | Default true: flows, connection references, environment variables and agents per environment, when a Dataverse sign-in is cached (cs_login) | |
| includeEnvironments | No | Default true; false captures tenant level only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares the tenant is never mutated, that only local files are written, that it runs as the admin account (profile/CPS_ADMIN_PROFILE), and that failures are isolated per capture and surfaced in 'skipped'. Missing only secondary traits like runtime or rate limiting.
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-loads the action and keeps to four sentences. The long artifact enumeration in sentence one is dense but earns its place by defining capture scope; nothing is obviously padding, though the list could be trimmed.
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 10-parameter tool with full schema coverage and no output schema, the description covers purpose, safety profile, auth prerequisite and partial-failure semantics adequately. It stops short of explaining the on-disk output layout an agent might want when chaining into a diff or source-control step.
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 every parameter including defaults and the 'created/overwritten' behavior of 'dir'. The description adds little beyond restating the profile handling, 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?
States a specific verb and resource ('Write the tenant's Power Platform configuration to local files') and enumerates the captured artifacts down to per-environment details, solutions, agents and backups. This clearly separates it from siblings like cs_snapshot_environment or cs_admin_backup_environment, which act on a single 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?
Gives concrete usage context ('for reference, diffing and source control') and clarifies scope (tenant-wide, read-only for the tenant). It does not, however, explicitly say when to prefer this over cs_snapshot_environment/cs_admin_backup_environment, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Point one of a flow's connection references at a real connection, which is the step that lets a flow be switched on. Picks the reference and the connection for you when there is only one of each, and asks when there is a choice. Handles both shapes: a flow that names a connection directly is edited in place, while a flow that came from a solution has its connectionreference row bound instead. Pass activate: true to turn the flow on in the same call once it is bound. Changes a live environment: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| flowId | Yes | Flow (workflow) id (cs_list_flows) | |
| search | No | Narrow the candidate connections by display name or owner | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| activate | No | Turn the flow on after binding; default false | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| connector | No | Connector id, e.g. shared_office365, to choose the reference by connector instead | |
| reference | No | Which connection reference to bind; only needed when the flow has more than one | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| connectionId | No | The connection to bind (its name from cs_list_connections); default: the only usable one for this connector | |
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does well: it discloses the confirm-required live-environment change and dry-run-without-confirm behavior, the in-place vs connectionreference row dual handling, and the automatic selection behavior. It omits failure/idempotency behavior, keeping it from a 5.
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, then progressively adds conditional behavior. Four dense sentences each carry information, though the passage is on the longer side for a single 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 12-parameter, annotation-free mutation tool with no output schema, the description covers the essential behavioral facts an agent needs (confirm gate, dual binding shapes, auto-selection, activate). It does not describe the return value or failure modes, a modest gap.
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 baseline is 3, but the description meaningfully augments it: it clarifies confirm as the gate for live changes (dry run otherwise), activate as the switch-on step, and describes the auto-pick logic that governs reference/connectionId/connector usage.
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 (bind/point) and resource (a flow's connection reference) and frames the scope precisely: it is 'the step that lets a flow be switched on'. This clearly distinguishes it from siblings like cs_create_connection, cs_update_flow, and cs_set_flow_state.
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?
Explains the workflow context and the auto-selection rule ('picks the reference and the connection for you when there is only one of each, and asks when there is a choice'), plus the activate flow. It lacks explicit when-not or named alternatives, 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.
Block an agent so nobody in the organisation can use it, or lift an existing block. This is a governance action across the whole tenant, not a deployment one: it does not unpublish or delete the agent, and it affects every user at once. Changes a live tenant: requires confirm: true. Needs the CopilotPackages.ReadWrite.All permission and runs against Graph beta, the only version that exposes it (cs_login scope 'graph_write'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Package id from cs_list_org_agents, e.g. P_19ae1zz1-56bc-505a-3d42-156df75a4xxy | |
| blocked | Yes | true blocks the agent for everyone, false lifts the block | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses confirm: true is required for a live change, the required permission (CopilotPackages.ReadWrite.All), the Graph beta / graph_write constraint, licence and global-cloud requirements, blast radius (affects every user at once), and that it is unverified. This is unusually rich disclosure 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?
Front-loads the core action and then packs prerequisite and constraint facts densely. It runs long, but nearly every clause earns its place given the mutation and environmental prerequisites; a slightly tighter grouping of the licensing/cloud constraints would help.
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 6-param mutation tool with no annotations and no output schema, the description covers the action, scope, prerequisites, dry-run behavior, and limitations, leaving nothing an agent needs to invoke it safely unstated.
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 every parameter including id, blocked, confirm, and the auth/workspace defaults. The description reinforces the confirm: true requirement but adds no syntax or format meaning beyond the schema, making the baseline 3 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 ('Block an agent ... or lift an existing block') and immediately scopes it as a tenant-wide governance action. It explicitly distinguishes itself from deployment/delete siblings by noting it 'does not unpublish or delete the agent', so an agent can tell it apart from cs_delete_agent or cs_quarantine_agent.
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?
Clear context: use this for whole-tenant governance blocking affecting every user, not deployment changes. It names the exclusion (not unpublish/delete) but does not explicitly name the sibling alternatives (e.g. cs_delete_agent) that an agent might otherwise reach for, so it stops short of full when-not/routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compose a Power Automate cloud flow definition from a step spec, without touching any environment: a trigger (agent-callable by default, or manual, HTTP, schedule or a connector trigger) plus steps (connector operations, HTTP calls, conditions, loops, scopes, variables, compose, terminate, response, or raw JSON). Steps run in order. Returns the definition, the connection references it needs and any notes, and can write it to a file. Feed the same spec to cs_create_flow to create the flow, or cs_update_flow to replace an existing one. Use cs_list_connectors and cs_describe_connector to find connector ids, operation ids and their parameters first.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| steps | No | Steps in order; each waits for the previous one to succeed | |
| outputs | No | What the flow answers with (agent-callable and HTTP flows) | |
| trigger | No | Default: 'agent' (When an agent calls the flow) | |
| outputFile | No | Write the definition JSON here as well | |
| description | No | ||
| connectionReferencePrefix | No | Prefix for generated connection reference names, usually your publisher prefix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does well: it says the tool does not touch any environment, returns the definition plus connection references and notes, and can optionally write to a file. It omits edge-case behavior such as invalid-spec handling, but for a pure builder tool the side-effect profile is clearly described.
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 front-loaded with the core purpose and the no-environment constraint. Each subsequent sentence adds routing or prerequisite information that helps an agent invoke the tool correctly, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex builder tool with no output schema and no annotations, the description covers the essential context: what it builds, what it returns, that it can write a file, and how it connects to cs_create_flow and cs_update_flow. The exact return shape is not detailed, but the description gives enough guidance for correct selection and invocation.
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 71%, so the schema documents many parameters, but the description adds useful meaning: the trigger defaults to 'agent', the supported trigger kinds are named, step categories are enumerated, and outputFile is described as an optional write target. It does not explain every parameter in depth, but it meaningfully supplements 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 states a specific verb and resource: compose a Power Automate cloud flow definition from a step spec. It distinguishes this from cs_create_flow and cs_update_flow by explicitly saying it does not touch any environment and only builds the definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing: use this tool to build a definition, then feed the same spec to cs_create_flow to create or cs_update_flow to replace an existing flow. It also names prerequisites by directing the agent to cs_list_connectors and cs_describe_connector for connector and operation ids.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one utterance to the published agent and return its replies (and raw activities). Use conversationId to continue. If the agent answers with a sign-in card, signInUrl is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| maxMs | No | How long to wait for replies, ms (default 25000, kept under the client call budget) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| transport | No | auto detects the agent's authentication mode via Dataverse; directline for no-auth/manual-auth agents; sdk for Entra SSO agents | |
| utterance | Yes | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| background | No | Run in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled. | |
| schemaName | No | ||
| dataverseUrl | No | ||
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| tokenEndpoint | No | Explicit DirectLine token endpoint | |
| conversationId | No | Continue an earlier conversation from cs_chat | |
| directLineSecret | No |
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 does disclose real behavior beyond the schema (return shape of replies/activities, the sign-in-card → signInUrl branch), but it is silent on auth requirements, the long-running/orphaning risk, and rate or timeout behavior that the agent would want to know.
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, front-loaded with purpose and then the continuation hint and the sign-in edge case. Every sentence carries information; the sign-in sentence is slightly peripheral but genuinely useful for a chat 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 14-parameter tool with no annotations and no output schema, the description is thin: it never explains the authentication modes, defaults, or the background/jobId escape hatch that the schema also flags. It partially compensates by naming the response fields, but a caller still needs to open the schema to use it safely.
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 71%, so most parameters are already self-documented, including conversationId, whose description matches the sentence in the tool description. The description adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a precise verb+resource pair ('Send one utterance to the published agent and return its replies') and clarifies the return surface with 'and raw activities'. It is clearly distinguishable from transcript/evaluation siblings on intent, though it never names an alternative explicitly.
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?
'Use conversationId to continue' is the only usage directive, which implies the multi-turn pattern but never states when to pick cs_chat over cs_run_conversation_tests or how to start a fresh vs. resumed conversation. Context is implied rather than argued.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find changes made directly in Copilot Studio after the workspace was last cloned, pulled or pushed. mode 'quick' (default) reads the agent's component rows from Dataverse and compares them with the sync stamp: which topics, tools and knowledge sources changed, by whom, when, whether the agent settings changed and whether there are unpublished changes; needs a cached cs_login, no pac. mode 'full' runs pac copilot clone into a temporary folder and classifies every file as local-modified, remote-modified or both (conflict) against the stamp, with unified diffs. Both are read-only. Resolve drift with cs_pull (three-way merge), then commit.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| keepClone | No | full: keep the temporary clone and return its path | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| includeDiffs | No | full: include unified diffs (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does so well: it states both modes are read-only, explains that quick reads Dataverse component rows and needs a cached cs_login without pac, and describes full mode running pac copilot clone into a temporary folder with file classification and diffs. It stops short of detailing cleanup behavior for the temporary clone or broader permission requirements, so it is strong but not exhaustive.
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 front-loads the core purpose before unpacking the two modes. Every sentence contributes operational detail, though the long semicolon-heavy midsection could be slightly easier to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no annotations and no output schema, the description covers the essential context: purpose, mode differences, authentication prerequisites, read-only behavior, and the follow-up resolution path. It reasonably describes what quick reports and what full classifies, though it leaves some parameter defaults and exact return-shape details to 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?
Schema coverage is high at 83%, so the schema already documents most parameters. The description nevertheless adds meaningful semantics for the critical mode parameter, explaining what quick and full actually do, what quick reads, what full produces, and the read-only nature of both.
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 gives a specific verb and resource: finding changes made directly in Copilot Studio after the workspace was last cloned, pulled, or pushed. It distinguishes the tool from resolution work by naming cs_pull and from authentication setup by referencing cs_login, so an agent can identify its role without checking 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 clearly explains when to run the check and how to act on results: resolve drift with cs_pull, then commit. It also distinguishes quick versus full modes and their prerequisites, though it does not explicitly state when not to use the tool or give a hard rule for choosing full over quick beyond the operational differences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyse solution zip files with the Power Apps Checker service (Solution Checker or AppSource Certification rule set) and write the results locally. Use as a quality gate before cs_deploy_solution. Runs 'pac solution check' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise). Only some inputs mutate; see the parameter descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| geo | No | Checker service geography | |
| path | No | Solution zip file(s); glob allowed | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| ruleSet | No | 'Solution Checker' (default), 'AppSource Certification' or a rule set id | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| clearCache | No | Clear the tenant's checker enforcement cache | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| saveResults | No | Store the results in the environment (Solution Health Hub) | |
| solutionUrl | No | SAS URL of a solution zip instead of path | |
| excludedFiles | No | Files to exclude from the analysis | |
| customEndpoint | No | Custom URL of the Power Apps Checker endpoint, instead of the geography's | |
| timeoutSeconds | No | Default 1800 | |
| outputDirectory | No | Where to write the results | |
| ruleLevelOverride | No | JSON file with rule level overrides |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses that it runs pac with the active auth profile, writes results locally, and—critically—that it mutates a live environment requiring confirm:true with a dry run otherwise, while flagging that only some inputs mutate. It doesn't detail which inputs mutate inline or describe permission requirements beyond the profile, so it falls short of the top mark.
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 tight sentences, front-loaded with purpose then routing then mutation semantics; each sentence earns its place. No padding or restated name.
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 16-parameter tool with no annotations and no output schema, the description covers the key operational facts an agent needs: purpose, ordering, auth profile, and the confirm/dry-run gate. It stops short of explaining return values or output format, though 'write the results locally' plus outputDirectory hint at it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 16 parameters thoroughly, making 3 the baseline. The description adds only a pointer ('see the parameter descriptions') and the confirm-gating rule rather than supplementing individual parameter meaning.
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 (Analyse) and resource (solution zip files) via the Power Apps Checker service, names the rule-set variants, and distinguishes itself by naming the sibling it precedes (cs_deploy_solution). An agent can tell this apart from cs_validate, cs_pack_solution, and cs_deploy_solution without opening a schema.
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 positions the tool as a quality gate to run before cs_deploy_solution, which gives clear when-to-use context and a named alternative gate. No when-not conditions are given, but the sequencing guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot clone: download an existing agent into a sync-connected workspace (a subfolder named after the agent under outputDir). Needs a pac auth profile. Records a sync stamp (.mcs/cs-sync.json) that cs_check_drift and the cs_push preflight compare against.
| Name | Required | Description | Default |
|---|---|---|---|
| bot | No | Agent id (GUID) or schema name; omit to be shown the agents in the environment | |
| outputDir | No | ||
| displayName | No | Folder name override | |
| environment | No | Environment id or URL; default active profile | |
| componentCollections | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the behavioral load. It discloses the auth requirement and a concrete side effect (records .mcs/cs-sync.json for cs_check_drift and cs_push preflight), but omits whether existing local folders are overwritten or what permissions are needed.
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 compact sentences, front-loaded with the core action; the prerequisite and side-effect details each add useful information without padding.
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 no annotations and no output schema, the description covers the critical auth prerequisite and sync-stamp side effect, but leaves componentCollections undocumented and does not explain sync-workspace setup or overwrite behavior, making it only minimally complete for a 5-parameter tool.
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 60%; the description clarifies outputDir as the parent of the agent-named subfolder but does not explain componentCollections or add much beyond the schema for bot, displayName, and environment.
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 (download/clone) and resource (an existing agent) and the destination (a subfolder named after the agent under outputDir). It clearly differentiates from creation/deletion siblings by being a clone-to-disk operation.
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?
Gives a prerequisite ('Needs a pac auth profile') and implies the context (a sync-connected workspace), but does not name alternatives like cs_pull or cs_extract_agent_template or state 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.
Export a solution from the environment and unpack it into a solution project folder (source-control layout). Read-only for the environment. Runs 'pac solution clone' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| map | No | Mapping XML file for component folders | |
| name | Yes | Solution unique name | |
| async | No | Run the operation asynchronously | |
| include | No | Settings to include in the export (pac solution export --include values) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| localize | No | Extract string resources into .resx files | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| packageType | No | Unmanaged, Managed or Both (default Both) | |
| timeoutSeconds | No | Default 3600 | |
| outputDirectory | No | Output directory | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does real work: it states 'Read-only for the environment' (disambiguating a 'clone' that writes only locally), names the underlying command 'pac solution clone', and notes it runs with the active pac auth profile. It omits overwrite behavior for an existing local folder and failure modes, but the read-only disclosure is the key trait an agent 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?
Three short sentences, front-loaded with the core action, then the safety trait, then the implementation detail. No filler and no repetition of schema 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?
For a 13-parameter tool with no annotations and no output schema, the description covers the essential unknowns: what it does, that it is environment-read-only, and the underlying pac command. It leaves the returned project path and the background/async jobId flow to the schema, which is acceptable, though a brief note on overwriting an existing project folder would complete the picture.
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% across all 13 parameters, including the profile defaulting chain and background/jobId polling, so the schema already does the heavy lifting. The description adds no parameter-level syntax or format detail beyond what the schema states, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Clone a solution') and immediately clarifies the mechanics: export from the environment then unpack into a solution project folder in source-control layout. This distinguishes it in substance from cs_pull_solution and cs_sync_solution, but it never names those siblings explicitly, so the differentiation is left to inference.
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?
Usage is only implied: the 'source-control layout' and project-folder framing hint at first-time project creation rather than updating an existing project, but there is no explicit when-to-use statement or named alternative (e.g., cs_pull_solution for refreshing an existing project). The read-only note gives partial context but does not route the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshot every environment in an ordered chain (e.g. DEV, TEST, ACC, PROD) and compare each adjacent pair. Returns one report per pair plus the first stage where drift appears. Snapshots go to /, reports to /reports.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | ||
| chain | Yes | ||
| agents | No | Agent schema names or ids to clone; default: every agent pac copilot list returns | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| solution | No | Solution unique name to record version/managed state for | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| maxAgents | No | Default 20 | |
| failOnDrift | No | ||
| includeDiffs | No | ||
| strictVariables | No | ||
| includeDataverse | No | Default true: flows, connection references, environment variables and publish state via Dataverse (needs cs_login; skipped silently otherwise) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior beyond structure: it writes snapshots to <dir>/<label> and reports to <dir>/reports (side effects with concrete locations), returns one report per adjacent pair, and surfaces the first stage where drift appears. It omits auth prerequisites (e.g. cs_login / MSAL clientId) and failure modes, which keeps it below 5.
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: core action first, then the return shape, then artifact locations. Every sentence carries information and there is no filler. Not quite a 5 because it is functional prose rather than tightly optimized.
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 11-parameter tool with no annotations and no output schema, the description adequately covers the overall flow and the return shape, which compensates for the missing output schema. It is still incomplete on prerequisites (Dataverse access needs cs_login per the schema), the semantics of the boolean flags, and failure behavior, leaving notable gaps for a 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 description coverage is mid-range (55%), so the schema handles roughly half the parameters. The description adds real meaning for two of them: 'chain' is explicitly ordered (adjacency defines the pairs compared) and 'label' drives the snapshot path under <dir>. However, the remaining booleans (failOnDrift, includeDiffs, strictVariables) and the dir/chain entries get no elucidation. A 3 is appropriate — partial compensation for the coverage gap.
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 concrete verb and resource: snapshot every environment in an ordered chain and compare each adjacent pair, with the canonical DTAP example (DEV, TEST, ACC, PROD) making the scope unambiguous. It does not name or distinguish itself from close siblings like cs_check_drift, cs_compare_snapshots, or cs_snapshot_environment, so it stops 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 DTAP-chain framing implies the scenario (comparing a promotion chain for drift), but there is no explicit when-to-use, when-not-to-use, prerequisite, or named alternative. An agent must infer that cs_check_drift and cs_compare_snapshots are the other options rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff a failed run against a successful one to separate a data problem from a logic problem. Names the action where the two runs part company, lists every action whose status differs, and flags actions present in one run but not the other, which means the definition changed between them. With compareTriggerData it also reports which top-level keys of the trigger payload differ (key names only, never the values). The baseline defaults to the most recent successful run. Read-only. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | The failed run (cs_list_flow_runs) | |
| flowId | Yes | Flow id (cs_list_flows) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| searchRuns | No | How far back to look for a successful baseline; default 50 | |
| baselineRunId | No | Run to compare against; default the most recent successful one | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| compareTriggerData | No | Also compare what the trigger handed each run |
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 so: declares read-only, names the backing service and cs_login scope 'flow', discloses the baseline-selection default, and warns it is unverified against a live tenant. It also reveals output semantics, including that trigger-data comparison reports key names only and never values.
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 purpose in the first sentence, then output semantics, then caveats. Every sentence contributes, though the middle sentence stacking three output behaviors is dense and could be trimmed slightly.
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 no-annotation, no-output-schema compare tool, the description covers purpose, output shape, defaults, auth scope, and a verification caveat, leaving nothing an agent needs to invoke it correctly. No return-schema explanation is required since the properties are described inline.
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, but the description adds real meaning beyond it: compareTriggerData is qualified as key-names-only (never values) and the baseline default is restated as behavior rather than a field. The remaining auth/workspace parameters are left to 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?
Names a specific operation (diff a failed run against a successful one) on specific resources, and spells out exactly what it produces: the diverging action, status-differing actions, and actions unique to one run. This is clearly distinguishable from siblings like cs_explain_flow_run or cs_get_flow_run without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the diagnostic context clearly (separate a data problem from a logic problem) and explains the baseline default (most recent successful run) plus the searchRuns window. It doesn't explicitly name or exclude the adjacent tools (cs_explain_flow_run, cs_analyze_flow_health), so the routing is implied rather than enumerated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offline diff of two snapshot folders: solution version, per-agent YAML differences (noise such as ids, audit info and connection ids removed), flows, connection references, environment variables, unpublished changes. Writes /-vs-.md and .json. failOnDrift returns an error result when drift is found (for pipeline gates).
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | Snapshot folder (earlier stage, e.g. DEV) | |
| b | Yes | Snapshot folder (later stage, e.g. TEST) | |
| reportDir | No | Default: parent of b | |
| failOnDrift | No | ||
| ignoredKeys | No | ||
| includeDiffs | No | Default true: unified diffs in the report | |
| strictVariables | No | Treat differing environment variable values as drift |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses that noise (ids, audit info, connection ids) is stripped, that it writes <reportDir>/<a>-vs-<b>.md and .json, and that failOnDrift turns drift into an error result. This is meaningful side-effect and error-behavior context 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?
A tight three-sentence paragraph that front-loads what is compared, then output locations, then the gate behavior. Nearly every clause carries information, with only mild density from the enumerated comparison targets.
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 no output schema, the description compensates by naming the two artifact files produced, and it explains the drift-gate return behavior. For a 7-parameter diff tool this covers what an agent needs, though a few parameters (ignoredKeys, strictVariables) remain unexplained.
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 71%, so the schema documents most parameters. The description adds context for reportDir (write location pattern) and failOnDrift (error-on-drift), but says nothing about ignoredKeys, includeDiffs, or strictVariables, leaving a gap it could have filled. 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 ('offline diff of two snapshot folders') and enumerates exactly what is compared (solution version, per-agent YAML, flows, connections, env vars, unpublished changes). The 'offline diff of folders' framing implicitly distinguishes it from live-environment siblings like cs_compare_environments, but no sibling is named explicitly.
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?
Usage is implied rather than stated: the reader infers this is for stage-to-stage folder comparison, and 'for pipeline gates' hints at the failOnDrift use case. However, there is no explicit when-to-use guidance or exclusion against cs_check_drift or cs_compare_environments, which the agent must disambiguate on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot init: create a new agent workspace on disk. Without 'environment' it is a local scaffold (no sign-in). With 'environment' it also creates the live agent and connects the workspace (needs pac auth profile and confirm: true). With 'solutionName' the agent is created inside that solution (existing unmanaged solution, or a new one with createSolution: true) via init, pack, import and clone; without it, pac puts the agent in a solution named after the agent. authoringMode 'classic' is the standard harness (topics, evaluations); 'cli-copilot' is the GitHub Copilot harness.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Agent display name | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| template | No | classic only | |
| background | No | Run in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled. | |
| projectDir | No | Folder for the agent's files, new or empty. Omit it to be offered one named after the agent. | |
| schemaName | No | ||
| environment | No | Environment id or URL to bootstrap into (creates a live agent) | |
| instructions | No | ||
| solutionName | No | Unique name of the solution to create the agent in (requires environment) | |
| authoringMode | No | ||
| createSolution | No | Create solutionName if it does not exist | |
| publisherPrefix | No | Publisher prefix, 2-8 lowercase letters or digits: it becomes part of every component's schema name and must match the publisher of the solution the agent lands in. Omit it to be shown the publishers in the environment and what the choice decides. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden well: it discloses the no-sign-in local path vs. the authenticated live path, the confirm:true requirement, and the multi-step solution pipeline (init, pack, import, clone). It could say more about failure modes or side effects on an existing workspace, but the safety-relevant behavior is well surfaced.
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 action, then dense conditional clauses that each carry real information. It is somewhat packed and long, but every sentence earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutation with no output schema and no annotations, the description covers the mode-switching parameters that actually determine behavior. Per-parameter details like background/jobId polling and publisherPrefix are left to the schema, which is acceptable given 75% coverage.
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 75%, and the description adds genuine cross-parameter meaning rather than repeating field docs: how 'environment' toggles the whole mode, that 'solutionName' requires environment and triggers createSolution semantics, and the behavioral difference between the two authoringMode values. This exceeds the baseline-3 case for well-covered schemas.
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 concrete verb ('create a new agent workspace on disk') with a clear resource and scope, and pins down the underlying mechanism ('pac copilot init'). It doesn't explicitly differentiate itself from near-siblings like cs_clone_agent or cs_create_agent_from_template, which keeps it from 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?
Gives clear conditional usage: omitting 'environment' produces a local scaffold with no sign-in, passing it creates a live agent requiring a pac auth profile and confirm:true, and 'solutionName' changes where the agent lands. It never names an alternative tool to use instead, so it falls short of explicit when-not/alternatives routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new agent in a solution from a template produced by cs_extract_agent_template. Runs 'pac copilot create' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| solution | Yes | Unique name of the solution to create the agent in | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| schemaName | Yes | Schema (unique) name of the new agent, e.g. contoso_HelpDesk | |
| displayName | Yes | Display name of the new agent | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| templateFile | Yes | Template YAML from cs_extract_agent_template | |
| timeoutSeconds | No | Default 900 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does most of it: it discloses that it runs 'pac copilot create', uses the active pac auth profile, mutates a live environment, and that omitting confirm:true yields only a dry run. It stops short of describing failure modes or follow-on effects (e.g. whether the agent must be published afterward).
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 tight sentences, front-loaded with the core action, then the mechanism, then the safety constraint. No sentence is filler and nothing is buried.
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 10-parameter mutating tool with no output schema and no annotations, the description covers the essential contract: what it creates, what input it needs, and the confirmation gate. Secondary operational details (background/jobId polling, timeoutSeconds, cwd) live in the schema and need not be repeated.
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 ten parameters including confirm, templateFile, profile and background are already documented in the schema. The description's 'requires confirm: true' and template provenance restate schema content rather than adding format or constraint detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (create a new agent in a solution) plus the qualifying input (from a template produced by cs_extract_agent_template), which cleanly separates it from cs_create_agent and cs_clone_agent. An agent can identify the right tool without opening the schema.
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 names the prerequisite producer tool (cs_extract_agent_template) and the confirm:true condition, which is actionable usage context. It does not explicitly state when to prefer this over cs_create_agent or cs_clone_agent, so routing still requires inference from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a pac authentication profile. Non-interactive: service principal (applicationId + clientSecret + tenant), certificate, managed identity, or GitHub / Azure DevOps federation. Interactive (a person signing in, which is the usual way to add an admin account): pass name, environment and background: true - pac opens its own browser, the call returns a jobId at once, and cs_job_status reports when the profile exists. Without background this blocks until the sign-in finishes and the client will usually give up first. Device code needs a terminal: this server gives pac no stdin. Runs 'pac auth create' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Profile name (max 30 characters) | |
| cloud | No | Cloud instance (Public, UsGov, UsGovHigh, UsGovDod, China) | |
| tenant | No | Tenant id (required with applicationId) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| password | No | Password (masked in logs) (masked in logs and results) | |
| username | No | User name for username/password auth (not recommended) | |
| background | No | Run in the background and return a jobId immediately. Use this for interactive sign-in: pac opens a browser and waits, which would otherwise outlive the client's call timeout. Poll cs_job_status. | |
| deviceCode | No | Use the device-code flow for interactive sign-in (blocks until done) | |
| environment | No | Default environment for the profile (id, URL, unique or partial name) | |
| clientSecret | No | Client secret (masked in logs) (masked in logs and results) | |
| applicationId | No | App registration (client) id | |
| timeoutSeconds | No | Default 600 | |
| githubFederated | No | GitHub federated credential (needs tenant and applicationId) | |
| managedIdentity | No | Use the default Azure identity | |
| certificateDiskPath | No | Certificate file for certificate auth | |
| certificatePassword | No | Certificate password (masked in logs) (masked in logs and results) | |
| azureDevOpsFederated | No | Azure DevOps federated credential (needs tenant and applicationId) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses that interactive mode opens pac's own browser, that background:true returns a jobId immediately, that foreground mode blocks past the client timeout, that device code requires a terminal this server cannot provide, and that the underlying command runs as the active pac auth profile. These are exactly the execution traits an agent 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?
Purpose is front-loaded and no sentence is pure filler, but the middle is dense with stacked parenthetical conditions (interactive, background, device code) that could be structured more cleanly. Still appropriately sized for an 18-parameter tool with complex execution modes.
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 18-parameter mutation tool with no annotations and no output schema, the description covers the hard parts: mode selection, blocking vs jobId behavior, the polling follow-up, and the stdin limitation. It does not explain the return payload beyond jobId or detail every credential combination, so it is strong but not exhaustive.
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 already 100%, so baseline is 3, but the description adds meaning beyond the schema: it groups parameters into auth modes (applicationId + clientSecret + tenant for service principal), explains why background exists and what it returns, and constrains deviceCode by the missing stdin. It stops short of mapping every credential parameter to its mode, but the added context is genuine.
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 pac authentication profile') and enumerates the supported auth modes, so an agent knows exactly what the tool does. It does not, however, explicitly contrast itself with sibling tools such as cs_select_auth_profile, cs_login, or cs_list_auth_profiles, so sibling differentiation is left implicit.
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 strong conditional guidance: non-interactive flows (service principal, certificate, managed identity, federation) versus interactive sign-in, and an explicit when/when-not for background:true ('Without background this blocks until the sign-in finishes and the client will usually give up first'). It names cs_job_status as the follow-up, but it does not name alternative sibling tools an agent might choose instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Dataverse connection that authenticates with an app registration (application id + client secret) so flows and tools owned by a pipeline do not depend on a person. This is the only connection kind pac can create; connector connections (SharePoint, Outlook, MCP servers ...) are still authorised in the portal. Runs 'pac connection create' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | Yes | Connection display name | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| tenantId | Yes | Entra tenant id | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| clientSecret | Yes | Client secret; prefer a secret from a vault, it is masked in logs (masked in logs and results) | |
| applicationId | Yes | App registration (client) id | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the burden; it discloses the mutation of a live environment, the mandatory confirm: true gate with dry-run fallback, and that it wraps 'pac connection create' under the active auth profile. Missing only the return/dry-run payload shape, which holds it back from a 5.
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 tight sentences, front-loaded with the purpose and immediately followed by the scope exclusion and the safety gate. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description covers the critical decision points (mutation safety, confirm gate, portal-only alternative) and leaves scheduling/timeout details to the schema. A note on what a dry run returns would make it 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 nearly all parameter meaning is already documented (confirm, profile, clientSecret masking, background, environment). The description adds only conceptual framing for applicationId/clientSecret rather than new per-parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource (create a Dataverse connection) plus the exact auth mechanism (app registration application id + client secret) and the motivating rationale (don't depend on a person). It also explicitly distinguishes this from connector connections, which cannot be created this way.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States plainly that this is the only connection kind pac can create and that connector connections (SharePoint, Outlook, MCP servers) must be authorised in the portal instead — an explicit when-not and alternative. It also names the dry-run-by-default condition that governs invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution create-settings: the JSON that maps every connection reference (to a connection id in the target environment) and environment variable (to a target value). Pass connectionReferences / environmentVariables to fill values; the result lists what is still unmapped.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Solution zip (or use solutionDir from cs_pull_solution) | |
| regenerate | No | Recreate the file even if it exists (mappings are lost) | |
| solutionDir | No | Directory written by cs_pull_solution | |
| settingsFile | No | Default <solutionDir>/deployment-settings.json or next to the zip | |
| copilotAgents | No | agent schema name -> Entra security group id allowed to use the agent in the target | |
| connectionReferences | No | logicalName -> connectionId in the target environment | |
| environmentVariables | No | schemaName -> value for the target |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the result lists still-unmapped items, which is useful, but it does not explain file creation/overwrite behavior, that mappings can be lost on regeneration, permission requirements, or other side effects of writing deployment settings.
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 largely front-loaded around the pac command and the settings JSON concept. The phrasing is slightly telegraphic, but it avoids repetition and wasted text.
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 core purpose and mentions the result listing unmapped values, which partly compensates for the missing output schema. Still, for a seven-parameter nested-object tool with no annotations, it omits important context about file behavior, defaults, and how this step fits into deployment workflows.
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 seven parameters, including nested objects and defaults. The description adds some meaning for connectionReferences and environmentVariables by explaining how they fill mappings, but it does not add semantic detail for the other 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 action tied to the pac solution create-settings command and identifies the resource: a deployment settings JSON mapping connection references and environment variables. It is clear enough to distinguish from most siblings, though it does not explicitly contrast with related deployment tools like cs_deploy_solution.
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 by saying to pass connectionReferences and environmentVariables to fill values, and that the result lists unmapped items. However, it does not state when to use this tool versus alternatives such as cs_pull_solution or cs_deploy_solution, nor does it give prerequisites or ordering guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Power Automate cloud flow, from a step spec (see cs_build_flow_definition: trigger plus connector, HTTP, condition, loop, variable and response steps) or from a ready-made definition, optionally straight into a solution. The flow is created switched off, because a flow can only be activated once its connection references are bound: bind them, then cs_set_flow_state on. To let an agent call it, use a trigger of type Request/kind Skills and add it as a tool with cs_add_tool type 'flow'. Changes a live environment: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Flow display name | |
| steps | No | Steps in order; each waits for the previous one to succeed | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| outputs | No | What the flow answers with (agent-callable and HTTP flows) | |
| trigger | No | Default: 'agent' (When an agent calls the flow) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| solution | No | Unique name of the solution to create it in | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| clientData | No | The whole clientdata document, when you have one (from cs_get_flow of another flow, for example) | |
| definition | No | A ready-made Power Automate definition, instead of steps | |
| description | No | ||
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| connectionReferences | No | properties.connectionReferences, when you pass a definition rather than steps | |
| connectionReferencePrefix | No | Prefix for generated connection reference names, usually your publisher prefix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the flow is created switched off, why (connection references must be bound first), that activating requires cs_set_flow_state, and that it changes a live environment requiring confirm: true. These are non-obvious behaviors an agent must know before calling.
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?
A single dense paragraph, front-loaded with the core action, and each sentence adds actionable information (creation mode, off-state, activation path, agent-tool wiring, confirm requirement). Slightly long but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter tool with nested step objects and no output schema, the description covers the essential workflow and the crucial create-off-then-bind-then-activate sequence. It does not detail return values, but that is a minor gap for a creation tool.
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 94%, so the schema already documents parameters like steps, definition, confirm, and connectionReferences. The description reinforces the steps-vs-definition distinction and the confirm requirement but adds little syntax beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new Power Automate cloud flow') and immediately clarifies the two input modes (step spec vs ready-made definition). It names the relevant sibling cs_build_flow_definition, so an agent can distinguish it from cs_update_flow and cs_add_flow without opening schemas.
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?
Gives clear routing context: use cs_build_flow_definition for the step spec, bind connection references before activating, then cs_set_flow_state, and use cs_add_tool to expose the flow to an agent. It does not state explicit exclusions (when NOT to create), but the alternative-naming is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new unmanaged solution (and its publisher if missing) in an environment by packing an empty solution manifest and importing it with pac. Use it to prepare the container before cs_create_agent with solutionName. Requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| workDir | No | Where the manifest and zip are written (default <workspace>/.cs-solutions/<uniqueName>) | |
| uniqueName | Yes | e.g. contoso_Agents | |
| displayName | No | ||
| environment | No | Environment id or URL. Defaults to the active pac auth profile. | |
| publisherName | No | ||
| publisherPrefix | Yes | 2-8 lowercase characters, e.g. contoso |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose useful traits: it is a mutating operation, it has an idempotent-ish side effect (creates the publisher if missing), it writes files to workDir, and it will only act for real when confirm: true is passed. It does not state what happens if the solution already exists, required permissions, or reversibility, which matters for a write 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?
Two tight sentences, front-loaded with the action and mechanism, followed by the routing guidance and the confirm gate. Little waste; the trailing 'Requires confirm: true' is slightly redundant with the schema but serves as an operational warning.
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 7-parameter write tool with no annotations and no output schema, the description covers the workflow, the side effect of publisher creation, and the dry-run gate. It leaves out idempotency behavior on an existing solution name, auth/environment prerequisites, and expected result, so it is adequate but incomplete.
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 71%, so the schema already documents environment, workDir, uniqueName format, and publisherPrefix constraints; the description only reinforces confirm and mentions solutionName (a parameter of the sibling cs_create_agent, not of this tool). Baseline 3 is appropriate since the schema does most of the semantic work.
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+resource ('create a new unmanaged solution') and adds the non-obvious scope note that it also creates the publisher if missing and does so by packing an empty manifest and importing it with pac. This is clearly distinguishable from siblings like cs_import_solution, cs_pack_solution, and cs_create_agent.
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?
Gives an explicit sequencing rule: 'Use it to prepare the container before cs_create_agent with solutionName.' That is real when-to-use guidance tied to a named sibling. It does not say when NOT to use it (e.g., how it relates to cs_import_solution or cs_clone_solution for pre-existing solutions), 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.
Write the CSV the portal's Evaluation page imports (columns Question, Expected response; max 100 cases). Test sets cannot be created through the API, so this file is imported once in the portal; runs and results are then automated via cs_run_evaluation. suggestFromWorkspace derives cases from topics, starters and knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| cases | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| outputPath | No | Default <workspace>/../<agent>-testset.csv | |
| maxSuggested | No | ||
| suggestFromWorkspace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the 100-case cap, the write-a-file-to-disk nature, and the crucial non-obvious constraint that the API cannot create test sets directly (portal import required). It omits overwrite behavior and any permission/error semantics, which keeps it from a 5.
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 tightly packed sentences, front-loaded with the core action and format. No filler, though the suggestFromWorkspace sentence could be clarified slightly more crisply.
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 5-parameter tool with no annotations and no output schema, the description covers the essential workflow (generate file, import once, automate runs afterwards). The remaining gaps (undefined maxSuggested, overwrite behavior) are minor but real.
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 only 40%, so the description must compensate. It meaningfully explains suggestFromWorkspace (derives cases from topics, starters and knowledge) and ties the max-100 limit to the cases list, but maxSuggested has neither schema nor description coverage, and cases/outputPath details rest on 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 verb (write) and resource (the CSV the portal's Evaluation page imports), and pins the artifact format (columns Question, Expected response) and size limit (max 100 cases). It clearly distinguishes itself from sibling evaluation tools by being a file generator rather than an API operation.
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?
Explains the key workflow context: test sets cannot be created via the API, so the file is imported once in the portal, after which runs are automated via cs_run_evaluation. This routes the agent well, though it doesn't explicitly contrast with cs_test_set_from_transcripts, the other likely test-set generator sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot delete: permanently delete an agent from the environment. Requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| bot | Yes | Agent id or schema name | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| environment | No | Environment id or URL. Defaults to the active pac auth profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the whole burden. It does disclose the two most important traits for a destructive tool: the deletion is permanent/irreversible and confirm: true is mandatory. It omits permission requirements and side effects on related components (flows, connections).
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 short clauses, front-loaded with the command and immediately followed by the destructive qualifier and prerequisite. No wasted words, though it is sparse enough that it reads more like a stub than a polished instruction.
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 tool with no annotations and no output schema, the essentials (permanence, confirm gate) are present, but nothing explains the dry-run return value, required auth/role, or the blast radius of the deletion. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already documents bot, confirm (including the dry-run behavior) and environment. The description only restates the confirm requirement, adding no syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('permanently delete an agent') plus the underlying CLI command, so the purpose is unambiguous. It does not differentiate from adjacent siblings like cs_quarantine_agent (reversible disable) or cs_delete_flow, so it stops 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?
'Requires confirm: true' is a useful operational prerequisite, implying this is not a default action. However there is no explicit when-to-use guidance, no statement of when NOT to delete (e.g. quarantine instead), and no mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a pac auth profile by index or name (local credential store only). Runs 'pac auth delete' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Profile name | |
| index | No | Profile index | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose a meaningful boundary: the deletion affects only the local credential store, not the tenant. However, it omits reversibility, whether the active profile can be deleted, and failure behavior for a mutation 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?
Two compact sentences, front-loading the operation and its scope before the implementation note. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-annotation mutation tool this is only minimally sufficient: purpose and scope are covered, but reversibility, active-profile constraints, and error handling are absent. The lack of an output schema is not a gap since the operation is a simple delete.
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 all six parameters are already documented. The description only restates that selection is by index or name, adding no format, precedence, or precedence-conflict details beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Remove') and resource ('pac auth profile') and narrows the selection to index or name. It also scopes the operation ('local credential store only'), which differentiates it somewhat from tenant-affecting siblings, though it does not name cs_select_auth_profile or cs_list_auth_profiles as alternatives.
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 or when-not-to-use guidance. An agent must infer from the name alone that this is the deletion counterpart to cs_create_auth_profile, and nothing tells it whether an active profile can be removed or what to do instead if deletion is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a connection by id. Flows and tools bound to it stop working until rebound. Runs 'pac connection delete' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| connectionId | Yes | Connection id (cs_list_connections) | |
| timeoutSeconds | No | Default 600 |
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 destructive side effects (bound flows/tools stop working), live-environment mutation, the underlying pac command/auth profile, and the confirm-to-execute behavior. It omits irreversibility and permission 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?
Four short sentences, front-loaded with the action. The consequence, command detail, and confirmation requirement each add distinct value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers purpose, side effects, confirmation, and auth context well. It omits irreversibility and return/error behavior, leaving minor gaps for a destructive tool.
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 seven parameters. The description only reinforces 'by id' and the confirm behavior, adding little beyond the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Delete' and resource 'connection' with scope 'by id', and notes the consequence for bound flows/tools, clearly distinguishing it from cs_create_connection, cs_update_connection, and cs_list_connections.
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?
Gives clear context for use: deleting a connection in a live environment, with the prerequisite that confirm: true is required (dry run otherwise). It does not name alternatives or when-not-to-use cases, so it falls 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.
Remove a cloud flow from the environment for good. Read it with cs_get_flow first: any agent tool that calls this flow will be left pointing at nothing, and a flow that is still switched on has to be turned off with cs_set_flow_state before Dataverse will delete it. A managed flow cannot be deleted this way; uninstall the solution it came in. Changes a live environment and cannot be undone: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| flowId | Yes | Flow (workflow) id (cs_list_flows) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
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: irreversible live-environment change, requires confirm: true, downstream agent tools left pointing at nothing, and the managed-flow restriction. That is well beyond what the schema declares.
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?
Dense but front-loaded: the destructive nature and prerequisites come before the confirm requirement. Three sentences each carry real information, though the packed clauses slow reading slightly.
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 tool with no annotations and no output schema, the description supplies the safety profile, prerequisites, and failure modes an agent needs to call it correctly. Nothing critical 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 all seven parameters are already documented; the description only echoes the confirm/dry-run semantics. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Remove a cloud flow from the environment for good') and clarifies the permanence, which distinguishes it from cs_set_flow_state or cs_delete_agent without needing to open any schema.
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 routes the agent: read with cs_get_flow first, turn the flow off with cs_set_flow_state before deletion, and use the solution-uninstall path for managed flows. Conditions that block this tool are stated outright.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution delete: delete an unmanaged solution container (its components stay in the environment) or uninstall a managed one (its components are removed). Requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Solution unique name | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| environment | No | Environment id or URL. Defaults to the active pac auth profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers the most consequential behavior: unmanaged deletes keep components in the environment while managed uninstalls remove them. It also flags the confirm:true requirement. It omits irreversibility and permission prerequisites, keeping it short of a 5.
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, with the pac command and the core managed/unmanaged distinction front-loaded and the confirm prerequisite trailing. No wasted words, though it is slightly dense in the parenthetical clauses.
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 tool with no annotations and no output schema, the description covers the critical behavioral distinction (container vs. uninstall) and the safety gate (confirm). It would be fully complete with a note on reversibility or required permissions.
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 all three parameters are already documented in the schema. The description restates the confirm requirement but adds no format or syntax detail 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 (delete) and resource (solution) and goes further by distinguishing the two deletion semantics: unmanaged container removal vs. managed uninstall. An agent can tell exactly what operation this performs without opening the schema.
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 clarifies the two modes and their effects, which helps an agent reason about consequences, but it never names alternatives or conditions for choosing this over siblings like cs_upgrade_solution or cs_list_solutions. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a pipeline deployment of a solution to a stage (the alternative to cs_deploy_solution when the tenant uses Power Platform pipelines). stageId comes from cs_list_pipelines. Runs 'pac pipeline deploy' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| wait | No | Wait until the deployment finishes | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| stageId | Yes | Deployment stage id (cs_list_pipelines with pipeline) | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| newVersion | Yes | Version to deploy as | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| solutionName | Yes | Solution unique name | |
| currentVersion | Yes | Current solution version | |
| timeoutSeconds | No | Default 3600 |
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 the tool mutates a live environment, that confirm: true is required with a dry run otherwise, and that it runs 'pac pipeline deploy' with the active pac auth profile. It does not cover failure/rollback behavior or permission boundaries beyond the active profile, so it is not fully complete.
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 tightly written sentences, front-loaded with the action and the safety-critical confirm requirement. Every sentence adds distinct value with no wasted text.
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 11-parameter mutation tool with no annotations and no output schema, the description covers purpose, alternative, stage source, and the safety gate. It omits behavioral details such as wait/background polling and failure handling, which keeps it from being 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 the baseline is 3. The description reinforces stageId's source and the confirm/dry-run semantics, but these are already documented in the schema; it adds no new format or constraint details beyond structured fields.
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: 'Start a pipeline deployment of a solution to a stage.' It explicitly distinguishes itself from the sibling cs_deploy_solution by naming the tenant condition that selects it, so an agent can choose without opening either schema.
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?
Names the alternative tool cs_deploy_solution and the condition for using this one (tenant uses Power Platform pipelines). It also points to cs_list_pipelines as the source of stageId, leaving no ambiguity about when and how to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution import into the target environment using the deployment settings file, then publish every Copilot Studio agent from the solution. Source: a zip, or a solutionDir from cs_pull_solution (managed zip preferred when present unless unmanaged: true), or an unpacked srcFolder (packed first). Blocks when connection references or environment variables are unmapped unless allowUnmapped. Requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ||
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| srcFolder | No | Unpacked solution folder to pack and deploy | |
| unmanaged | No | With solutionDir: deploy the unmanaged zip instead of the managed one | |
| solutionDir | No | ||
| settingsFile | No | ||
| allowUnmapped | No | ||
| publishAgents | No | Default true: pac copilot publish for each agent after import | |
| forceOverwrite | No | ||
| stageAndUpgrade | No | ||
| skipLowerVersion | No | ||
| targetEnvironment | Yes | Environment id or URL to deploy into | |
| maxAsyncWaitMinutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does disclose real traits: it blocks on unmapped references, requires confirm:true to mutate (otherwise a dry run) and publishes agents by default. It stops short of auth/permission prerequisites, error semantics, or async/job behavior, so the disclosure is solid but not exhaustive.
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?
A single dense paragraph, front-loaded with the core action, followed by source selection and blocking/confirm conditions. Nearly every clause carries information, though the packed sentence structure makes it slightly heavy to parse.
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 13-param deployment tool with no output schema and no annotations, the description covers the main flow, source selection, blocking conditions and the confirm gate well. It omits the four undocumented flags and any indication of what the call returns, leaving modest gaps against the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 38%, so the description must compensate, and it does for most params: zip, solutionDir (from cs_pull_solution), unmanaged (true), srcFolder (packed first), settingsFile, allowUnmapped, confirm, and publishAgents. It leaves forceOverwrite, stageAndUpgrade, skipLowerVersion and maxAsyncWaitMinutes unexplained, so compensation is substantial but 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?
Specific verb+resource+target: 'pac solution import into the target environment ... then publish every Copilot Studio agent'. It also enumerates the accepted sources (zip, solutionDir, srcFolder) and names the sibling cs_pull_solution as the producer, so an agent can distinguish it from cs_import_solution/cs_pack_solution without opening the schema.
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?
Gives clear conditional guidance: managed zip is preferred unless unmanaged:true, srcFolder is packed first, and it blocks on unmapped connection references/env vars unless allowUnmapped. It does not, however, state when to choose this over cs_import_solution or cs_deploy_pipeline, so the when-not side is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch (or read from cache) a connector's OpenAPI definition and list its operations with operationId, parameters (required, type, description) and response fields; marks MCP-capable connectors (x-ms-agentic-protocol). Exactly what cs_add_tool needs. Cached under .cs-catalog//connectors/.json and used by cs_validate.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| connector | Yes | shared_<name> or a display name | |
| operation | No | Filter operations by id or summary | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| includeInternal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior beyond the schema: the fetch-or-cache semantics, the cache location (.cs-catalog/<environment>/connectors/<name>.json), and the MCP-capable marking. It does not mention auth/permission requirements for the credentialed paths, but for a read-oriented describe tool this is solid disclosure.
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-loads the core action and then packs output shape, MCP marking, consumer relationship, and cache path into a tight two-sentence block. Dense but every clause earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe returns, and it does (operationId, parameters, response fields). Combined with the cache path and the cs_add_tool/cs_validate relationships, it is complete enough for an agent to call a read tool with one required parameter.
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 75%, so the schema already documents most parameters (clientId, tenantId, workspace, environmentId defaults). The description adds only the caching angle behind 'refresh' and does not explain filter semantics for 'operation' or 'includeInternal', so it sits at the baseline where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (fetch a connector's OpenAPI definition) and precisely enumerates the output (operationId, parameters with required/type/description, response fields). It differentiates from siblings like cs_list_connectors by scoping to a connector's operations, and flags the MCP-capable marker (x-ms-agentic-protocol).
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?
"Exactly what cs_add_tool needs" gives a clear when-to-use anchor and the cs_validate relationship adds context. It stops short of explicit when-not-to-use conditions or naming an alternative describe tool, so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a solution (unmanaged, async) and unpack it locally, then inventory everything inside: agents (with harness and component counts), bot components by kind, cloud flows, connection references, environment variables, custom connectors, other component folders. Read-only for the environment.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Solution unique name | |
| workDir | No | Where to put the export and unpacked source (default <workspace>/.cs-solutions/<name>) | |
| environment | No | Environment id or URL. Defaults to the active pac auth profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the export is unmanaged, that it runs asynchronously, that it unpacks locally, and that it is read-only against the environment. It stops short of naming auth prerequisites or rate/throughput limits, but the mutation and safety profile is substantively conveyed.
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?
It is a single dense sentence that front-loads the core action (export + unpack) before the inventory list, so the most important information appears first. It is information-rich rather than padded, though the component enumeration is long.
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?
There is no output schema, but the description compensates by enumerating the inventory contents an agent will receive (agents with harness/component counts, bot components by kind, flows, connection references, etc.). Combined with the async/read-only disclosure, this is nearly complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so name, workDir, and environment are already documented in the schema; the description adds no format, default, or validation detail beyond them. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a concrete verb sequence (export unmanaged + async, unpack locally, inventory contents) and enumerates the resource types produced (agents, bot components, cloud flows, connection references, environment variables, custom connectors). This clearly distinguishes the tool's inventory-oriented output from generic list tools, though it never names a specific sibling to contrast against.
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 exclusion relative to the many solution siblings (cs_list_solutions, cs_pull_solution, cs_pack_solution, cs_sync_solution). The only guidance-like line, 'Read-only for the environment,' describes a safety trait rather than a selection condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inventory of an agent workspace: settings, instructions, topics (with trigger phrases), knowledge sources, tools, flows, triggers, variables, connection references, sync metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. 'Inventory' strongly implies a read-only, non-mutating operation and the enumeration tells the agent the breadth of what is returned, which is genuinely useful. However, it never states read-only semantics outright, nor mentions permission/auth requirements, response size, or truncation behaviour for a workspace that may contain many components.
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?
A single front-loaded sentence with a dense enumeration and no filler. It is efficient, though it is a fragment and the parenthetical about trigger phrases is the only structural detail.
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 one-parameter, read-only inventory tool with no output schema, enumerating the returned component categories effectively substitutes for a return-value description. The main residual gap is the absence of any note on read-only semantics or output volume, which the missing annotations would otherwise have 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?
One optional parameter with 100% schema description coverage, so the schema already documents that 'workspace' accepts a path inside the workspace and defaults to CPS_WORKSPACE or cwd. The description adds nothing about this parameter, which is the expected baseline when the schema does the work.
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 the resource (an agent workspace) and enumerates exactly what the tool surfaces — settings, instructions, topics, tools, flows, triggers, variables, connection references. It is a noun-phrase inventory rather than a verb+resource statement, and it never explicitly distinguishes itself from near-siblings like cs_status or cs_describe_solution, but the scope is 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?
There is no guidance on when to reach for this tool versus cs_status, cs_list_agents, or cs_describe_solution, nor any prerequisite or exclusion. The agent must infer usage purely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'give me the Teams app package for this agent': download the channel manifest zip (manifest.json plus icons) for an agent published to the Microsoft 365 and Teams channel, the same file the portal offers as 'Download .zip', for sideloading or the Teams admin centre. Writes only the zip file; nothing in the environment changes. The agent must already be published to that channel. Follows the published Power Platform API reference; not yet verified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| channel | No | Channel name; M365 is the only one the API supports today | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| outputPath | No | Where to write the zip. Default: beside the workspace, else the temp folder | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| includeAgentSchema | No | Also put the agent schema in the package |
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 write scope ('Writes only the zip file; nothing in the environment changes'), the exact artifact contents ('manifest.json plus icons'), and a candid reliability caveat ('not yet verified against a live tenant'). It does not mention the MSAL sign-in/auth state the clientId/tenantId parameters imply, which is the remaining 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?
One front-loaded paragraph that opens with the user intent, then narrows to scope, side effects and the verification caveat. Dense but every clause carries information; the only mild redundancy is restating the portal's 'Download .zip' label alongside the artifact contents.
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, all-optional, no-output-schema tool, it covers the essential unknowns: prerequisite publishing state, non-destructive side effects, artifact contents, and provenance of the API contract. It could additionally state the auth/login requirement implied by the MSAL parameters, but otherwise an agent has what it needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 8 parameters, so defaults, the M365 enum and environment fallbacks are already documented in the schema. The description adds only the artifact-level detail (manifest.json plus icons) and does not clarify parameter interactions or syntax beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('download the channel manifest zip ... for an agent published to the Microsoft 365 and Teams channel') and equates it to a user-facing artifact ('the same file the portal offers as Download .zip'). This clearly separates it from packaging siblings such as cs_pack_solution or cs_pack.
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?
Gives an explicit trigger phrase ('give me the Teams app package for this agent'), the use cases (sideloading, Teams admin centre) and the hard prerequisite that the agent must already be published to that channel. It stops short of naming a sibling alternative for the non-M365 case, so it is not a full when/when-not routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'what exactly did that evaluation run test?': download the agent content snapshot the run was scored against, as the service zipped it, so it can be compared with the workspace now (unzip, then cs_compare_snapshots or a file diff). Writes only the zip file; the environment is not touched. Follows the published Power Platform API reference; not yet verified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| runId | Yes | cs_list_evaluation_runs shows the ids | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| outputPath | No | Where to write the zip. Default: beside the workspace, else the temp folder | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does well: it states the only side effect ('writes only the zip file; the environment is not touched') and adds a reliability caveat ('not yet verified against a live tenant'). It omits auth prerequisites and error behavior for a missing/unscored run, keeping it shy of 5.
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-loads purpose via the quoted question, then gives side effects and the caveat compactly. Two long sentences carry several facts; slightly dense but each 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 7-param, 1-required download tool with no output schema or annotations, the description covers purpose, side effects, and next step adequately; the zip is the return value, so no output explanation is needed. Auth/error semantics remain the only unaddressed area.
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 seven parameters are already documented in the schema; the description adds only the notion that outputPath receives a zip. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (download) and a precise resource (the agent content snapshot an evaluation run was scored against), with the run-scoping target made explicit. It is clearly distinguishable from siblings like cs_compare_snapshots and cs_list_evaluation_runs, which operate on snapshots/runs rather than downloading one.
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?
Frames the use case sharply ('what exactly did that evaluation run test?') and points to the follow-up (cs_compare_snapshots or a file diff), giving clear context for when to reach for it. It does not state exclusions or alternatives (e.g., cs_get_evaluation_run for metadata only), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a knowledge source file: name, description, site URL, includeSubPages, trigger condition (null removes it), additional search terms. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | ||
| rename | No | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| knowledge | Yes | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No | ||
| includeSubPages | No | ||
| triggerCondition | No | ||
| additionalSearchTerms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it discloses the dry-run default, that the first call returns a diff of the files it would write for user approval, that confirm: true is required to actually persist changes, and that null on trigger condition removes it. These are the exact behavioral traits an agent needs before invoking a mutation.
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 editable fields and then the critical two-phase write workflow. Every sentence adds information an agent needs; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the write semantics, the approval gate, and the preview return value. It omits permission/auth requirements and the meaning of the required knowledge parameter, but the operationally risky behavior is fully addressed.
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 22%, so the description must compensate, and it does: it maps name/rename, description, site URL, includeSubPages, triggerCondition, and additionalSearchTerms, including null-removes semantics for the latter two. It leaves the required 'knowledge' parameter unexplained and uses 'name' where the schema says 'rename', so it falls short of 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?
States a specific verb ('Change') and resource ('a knowledge source file') and enumerates the editable fields, which cleanly separates it from the sibling cs_add_knowledge_source. An agent can identify the tool's scope without opening the schema.
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?
Gives explicit invocation guidance: the first call is a no-op preview, and the write only happens on a second call with the same arguments plus confirm: true. It does not, however, route the agent between this tool and alternatives such as cs_add_knowledge_source for creating new sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change an existing tool file: name, description, modelDescription / modelDisplayName (what the orchestrator routes on), operationId, connection mode or reference, output mode, and inputs (set / add / remove). Validates afterwards. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | Tool name, file stem or path | |
| rename | No | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| addInputs | No | ||
| setInputs | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| outputMode | No | ||
| description | No | ||
| operationId | No | ||
| removeInputs | No | propertyNames to drop | |
| connectionMode | No | ||
| modelDescription | No | ||
| modelDisplayName | No | ||
| connectionReference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to lean on, the description carries the burden well: it discloses the two-phase commit (first call is a no-op dry run returning a diff, second call with confirm:true writes), that validation runs afterward, and that user approval is expected. It omits any mention of auth/permission requirements or reversibility, but the mutation safety profile is unusually well explained.
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 resource being changed, then the field list, then the two-phase confirm workflow. The parenthetical about orchestrator routing earns its place. Slightly dense but no filler 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 14-parameter mutation tool with no annotations and no output schema, the description covers the essential behavioral contract (what changes, the preview/confirm flow, validation) that the schema cannot. Minor gaps remain around workspace targeting and how rename/removeInputs interact, but the definition is serviceable for correct invocation.
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 low (29%), so the description must compensate, and it largely does: it maps the changeable attributes (name via rename, description, modelDescription/modelDisplayName, operationId, connectionMode/connectionReference, outputMode, and input set/add/remove) and clarifies that modelDescription/modelDisplayName drive routing and that inputs have set/add/remove variants. It adds genuine meaning beyond the bare schema, though workspace and confirm semantics come mostly from 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 verb and resource ('Change an existing tool file') and enumerates the mutable fields, including what modelDescription/modelDisplayName control (orchestrator routing). It implies the distinction from cs_add_tool (create) but never names a sibling to route the agent explicitly.
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?
Usage is implied rather than stated: the agent can infer this is for modifying an existing tool, since it says 'existing tool file.' However, no alternatives are named (e.g., cs_add_tool for new tools, cs_set_tool_preset for presets), so the when-to-use-vs-siblings dimension is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change an existing topic in place, keeping its comment header: rename, description, trigger phrases (set / add / remove), priority, append or insert nodes (same node spec as cs_add_topic), remove top-level nodes by id. Validates the file afterwards. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic name, file stem or path | |
| rename | No | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| priority | No | null removes the priority | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| description | No | ||
| appendActions | No | ||
| insertActions | No | ||
| removeActionIds | No | ids of top-level nodes (see cs_describe_workspace or the file) | |
| addTriggerPhrases | No | ||
| setTriggerPhrases | No | ||
| removeTriggerPhrases | No |
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 non-obvious two-phase preview/confirm protocol, that validation runs afterward, that the comment header is preserved, and that null priority removes the value. These are exactly the behaviors an agent would otherwise get wrong.
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 primary action, then the confirm protocol. Mostly dense and efficient, though the parenthetical '(same node spec as cs_add_topic)' and the trailing confirm sentence slightly stretch length for a definition that could tighten.
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 mutation tool with nested objects and no output schema, the description gives a coherent mental model: preview-then-confirm, validation, preserved header. It covers the return of the first call (diff/character count) but says little about failure modes or the second call's response.
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 only 42%, but the description compensates by naming most functional parameters and their modes (set/add/remove trigger phrases, append vs insert actions, remove by top-level id, null priority). It still leaves topic, workspace and the node structural params to the schema, which is acceptable since the schema documents those.
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+resource ('Change an existing topic in place') and enumerates exactly what can be edited: rename, description, trigger phrases, priority, node append/insert/remove. It also points to cs_add_topic for the shared node spec, so an agent can distinguish it from its closest 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 explains the two-call workflow: the first call previews a diff and changes nothing, and the same call with confirm:true writes. It implies the edit-vs-add split by referencing cs_add_topic, but does not state explicit conditions for choosing this over other mutators.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a FetchXML query against Dataverse through pac (read-only), e.g. to inspect bot or botcomponent rows without an MSAL sign-in. Runs 'pac env fetch' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| xml | No | FetchXML query text | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| xmlFile | No | File containing the FetchXML query | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose that the operation is read-only, runs through pac, uses the active pac auth profile, and avoids MSAL sign-in. However, it does not describe return behavior, error conditions, permission requirements, or query-cost considerations.
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: the first sentence states the action, target, and read-only nature; the second adds the concrete mechanism and example. Every sentence contributes useful context without 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?
With seven parameters, no annotations, and no output schema, the description does a reasonable job of covering purpose, auth context, and read-only behavior. It does not explain what the query returns or how results are shaped, and it does not route the agent among related query tools, leaving gaps for an agent invoking it in a large sibling set.
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 itself documents all seven parameters in detail. The description reinforces the active pac auth profile and XML query concept but adds little parameter-level meaning beyond what the schema already 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 gives a specific verb and resource: run a FetchXML query against Dataverse through pac. It also frames it as read-only and mentions an example use case, inspecting bot or botcomponent rows without MSAL sign-in. It does not explicitly differentiate the tool from sibling query-related tools such as cs_admin_query, but the core purpose is 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 example 'to inspect bot or botcomponent rows without an MSAL sign-in' implies when the tool is useful, but it does not state when to use it instead of alternatives like cs_admin_query or cs_lookup_schema. There are no exclusions or prerequisite guidance beyond the active pac auth profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Environments visible to the active pac auth profile. The pac-based alternative to cs_list_environments, which needs a cs_login. Runs 'pac env list' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| filter | No | Only environments whose name contains this text | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the underlying mechanism ('Runs pac env list') and the auth dependency on the active pac auth profile, but says nothing about the read-only/non-destructive nature, failure modes when no profile is active, or what the call returns.
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, front-loaded sentences with no filler. The closing sentence repeats the 'active pac auth profile' already established in the first, a minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description should ideally say what a successful call yields and how the pac profile dependency behaves. It covers the auth angle well but leaves the return shape and edge cases unspecified for a 5-parameter tool.
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 (cwd, filter, profile, background, timeoutSeconds) are already documented in the schema. The description adds no syntax or behavioral detail beyond the schema, 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?
States a specific verb and resource ('Environments visible to the active pac auth profile') and explicitly positions itself against the sibling cs_list_environments. An agent can distinguish the two without opening either schema.
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?
Names the alternative (cs_list_environments) and the condition that separates them ('which needs a cs_login'), implying this tool is the one to pick when no cs_login is available. The selection rule is clear but left slightly implicit rather than stated as an explicit 'use this when...' instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the environment that pac commands use when none is passed (local profile setting). Runs 'pac env select' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | Yes | Environment id, URL, unique or partial name | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does add useful context: this mutates a LOCAL profile setting and runs 'pac env select' against the active auth profile, so the agent knows it is not a cloud-side change. It omits idempotency, which profile is affected, whether it errors when no auth profile is active, and any auth/permission 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?
Two tight sentences, front-loaded with the effect and followed by the underlying mechanism. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple local-config mutation with full schema coverage and no output schema, the description conveys purpose, mechanism, and scope adequately. It could note that the setting is profile-scoped and whether it requires an authenticated profile, but nothing critical for correct invocation 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 schema already documents all five parameters including environment, profile, cwd, background, and timeoutSeconds. The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Set) plus the exact resource and scope: the default environment pac commands use when none is passed, qualified as a local profile setting. This cleanly distinguishes it from read-oriented siblings like cs_env_list, cs_env_who, and cs_env_fetch, and from cs_select_auth_profile (which selects an auth profile, not an 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 phrase 'when none is passed' implies the use case (establishing a default so later pac commands don't need an explicit environment), but there is no explicit when-to-use/when-not guidance, no prerequisites, and no named alternative. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Organisation id, URL, version and the signed-in user for an environment. Runs 'pac env who' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It usefully discloses the underlying command ('pac env who') and that it uses the active auth profile, and lists returned fields, but it does not state that the operation is read-only, describe auth prerequisites, or mention error 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?
Two short sentences with no wasted text; the returned fields are front-loaded and the execution detail follows. Slightly telegraphic but appropriately sized.
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?
No output schema exists, so the description compensates by listing the returned fields. Combined with the fully described input schema, this is mostly complete for a simple environment-info command, though usage guidance and explicit safety context are thin.
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 input schema already documents each parameter. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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 what the tool returns—organisation id, URL, version, and signed-in user—for an environment. It is specific about the resource and output but does not explicitly contrast itself with siblings like cs_env_list or cs_auth_who.
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?
Usage is implied by the purpose and by the note that it runs 'pac env who' with the active pac auth profile. There is no explicit when-to-use guidance, no exclusions, and no named alternatives such as cs_env_list or cs_auth_who.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Why one run of a cloud flow failed, in terms of the action that broke and what it was given. For each failed action it resolves the real error message - a failed connector action carries no error of its own, so the message is fetched from the action's outputs - classifies the failure as a connector, expression or timeout problem, and returns the inputs it was called with plus the outputs of the actions that ran just before it. Read-only. Start here when cs_list_flow_runs shows a failure. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | Run id (cs_list_flow_runs) | |
| flowId | Yes | Flow id (cs_list_flows) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| includeInputs | No | Fetch each failed action's inputs as well; default true | |
| upstreamCount | No | Succeeded actions to include with their outputs, ending at the first failure; default 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the whole burden and does so well: it declares read-only, explains the non-obvious mechanic that a failed connector action carries no error of its own and the message must be fetched from the action's outputs, names the required auth scope (cs_login scope 'flow'), and honestly flags 'Unverified against a live tenant.' It stops short of rate limits or what happens when a run did not fail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the purpose before the mechanism, trigger, auth and caveat. Dense but every sentence carries information; the mid-sentence clause on error resolution is the only slightly heavy part.
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?
No output schema exists, and the description adequately sketches the return payload (resolved error message, classification, action inputs, upstream outputs) plus auth and trigger context. It omits only edge behavior such as what is returned or raised when the run did not fail, which is minor for a diagnostic tool.
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 eight parameters including defaults; baseline is 3. The description adds only soft meaning for includeInputs and upstreamCount by describing the returned inputs/upstream outputs, but no format, syntax or selection guidance beyond the schema's own defaults.
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 (explain) plus resource (one flow run) and scopes it precisely: 'why one run of a cloud flow failed, in terms of the action that broke and what it was given.' That framing distinguishes it from cs_get_flow_run (raw run data), cs_analyze_flow_health (aggregate health) and cs_compare_flow_runs (diffing), which an agent can see without opening any schema.
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?
Gives an explicit entry condition: 'Start here when cs_list_flow_runs shows a failure,' which routes the agent from a sibling cleanly. However it names no exclusions or alternative diagnostic tools (e.g. health analysis for recurring/aggregate failures), so it is clear context without full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a reusable YAML template from an existing agent (its topics, settings and components), for cs_create_agent_from_template in another environment or solution. Runs 'pac copilot extract-template' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| bot | Yes | Agent id or schema name | |
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| overwrite | No | Overwrite the file if it exists | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| templateFile | Yes | Path of the YAML template to write | |
| templateName | No | Template name (default kickStartTemplate) | |
| timeoutSeconds | No | Default 600 | |
| templateVersion | No | Template version X.Y.Z (default 1.0.0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden. It discloses the actual mechanism ('pac copilot extract-template') and that it runs under the active pac auth profile, which is useful context, but says nothing about write side effects on disk, failure modes when the agent or profile is missing, or what the returned jobId/file looks like.
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: the first front-loads the action and its output, the second supplies the execution mechanism. No filler and nothing repeated from the 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 10-parameter extraction tool with no annotations and no output schema, the description covers purpose, the round-trip sibling and the auth context adequately, and the fully-covered schema handles parameter details. The only gap is behavioral disclosure around overwrite/permissions, which the absent annotations leave unaddressed.
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 every parameter including bot, templateFile, overwrite, background and profile is already documented in the schema; the baseline is 3. The description adds no per-parameter detail beyond noting the template's contents, so it does not exceed 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?
Specific verb plus resource: writes a reusable YAML template capturing an existing agent's topics, settings and components. It names the exact round-trip counterpart (cs_create_agent_from_template) and the underlying command, so an agent can distinguish this from siblings like cs_clone_agent or cs_pull without opening any schema.
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: use this to produce a template intended for another environment or solution, via cs_create_agent_from_template. It stops short of stating exclusions (e.g. when to clone instead of templating), but the intended workflow is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the localisable strings of one or all agents as .resx or .json files, from the environment or from an unpacked solution folder. Runs 'pac copilot extract-translation' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Write files for every supported language, not only the primary one | |
| bot | No | Agent id or schema name; omit for every agent | |
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| format | No | resx (default) or json | |
| outDir | No | Output directory | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| overwrite | No | Overwrite existing files | |
| sourceDir | No | Unpacked solution folder to read instead of the environment | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 900 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that it shells out to 'pac copilot extract-translation' and runs under the active pac auth profile (implying auth is required), but says nothing about what it writes, whether existing files are clobbered by default, or that long runs can be backgrounded.
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 tightly written sentences with zero filler: the capability and its scope lead, and the implementation/auth detail follows. Every clause carries information an agent can act on.
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 11-parameter CLI wrapper with no output schema and no annotations, the description covers the essentials (what is exported, formats, sources, underlying command, auth context). It could have said what the tool returns or where files land, but the schema's outDir/background descriptions partly compensate.
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 11 parameters including formats, sources, profile resolution, and the background/jobId behaviour. The description restates format and source options at a high level without adding syntax or defaults beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Export) and resource (localisable strings of one or all agents) plus the two output formats, so the operation is unambiguous. It does not explicitly contrast itself with the nearby sibling cs_merge_translations, which is the closest tool an agent could confuse it with, 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?
"from the environment or from an unpacked solution folder" implies the two source modes (environment vs sourceDir) but never states when to prefer one, nor any prerequisites or exclusions. There is no explicit routing to or away from cs_merge_translations or cs_extract_agent_template, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write the agent's instructions for it - the system prompt that decides how it answers. Builds a brief from purpose, audience, tone, capabilities, boundaries and examples, send it to an AI Builder prompt or model (pac copilot model predict; pick one with cs_list_prompts), and return the generated instructions. With apply: true the text is written into the agent's instructions (agent.mcs.yml, or settings.mcs.yml for cli-copilot), and only with confirm: true as well - without it the generated text comes back with the change it would make and the character count, and nothing is written. Pass currentInstructions/changeRequest (or refine: true to read the workspace) to revise existing instructions instead.
| Name | Required | Description | Default |
|---|---|---|---|
| tone | No | ||
| apply | No | Write the result into the agent instructions (needs confirm: true as well) | |
| refine | No | Revise the workspace's current instructions using changeRequest | |
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| modelId | No | ||
| purpose | No | What the agent is for; required unless refining | |
| audience | No | ||
| examples | No | ||
| language | No | ||
| inputMode | No | ||
| modelName | No | Full or partial AI Builder model / prompt name | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| boundaries | No | ||
| environment | No | Environment id or URL. Defaults to the active pac auth profile. | |
| capabilities | No | Default: derived from the workspace (topics, knowledge, tools) | |
| changeRequest | No |
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: it names the exact files written (agent.mcs.yml, settings.mcs.yml for cli-copilot), the confirm gate that prevents writes, and the precise no-write behavior (changed lines plus character count). This is exactly the destructive-action context an agent 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?
Front-loads the core purpose and keeps every sentence substantive, but the second sentence is a long run-on bundling build, send, write, and revise modes together. Splitting it would improve scannability without adding 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?
No output schema and no annotations, so the description must carry behavior on its own; it covers the write/preview contract and the model-selection prerequisite well. It stops short of explaining the remaining generation-shaping parameters (tone, language, examples, inputMode), which leaves some gaps for a 16-parameter tool.
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 only 50% across 16 params, and several (tone, audience, language, examples, boundaries, modelId, inputMode) have no description anywhere; the description partially compensates by naming the brief components it derives from and by spelling out the apply/confirm/refine interplay. Minor flaw: it references currentInstructions, which is not present in the input 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?
Starts with a concrete verb and resource ('Write the agent's instructions … the system prompt'), then explains the build-and-generate pipeline. An agent can distinguish this from cs_update_agent or cs_add_topic without opening any other schema.
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?
Gives explicit conditions: use cs_list_prompts to pick an AI Builder prompt/model, set apply:true plus confirm:true to write, omit confirm to preview, or pass changeRequest/refine:true to revise existing instructions. The alternative path (refine vs. fresh generation) is named, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'do users have to approve this agent's connectors?': read whether an admin has switched connector consent bypass on for the agent, so its connector tools run without each end user consenting to the connection first. Read-only. cs_set_connector_consent_bypass is the separate step that changes it. Follows the published Power Platform API reference; not yet verified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it declares 'Read-only', explains the operational meaning of the flag (connector tools run without each end user consenting), and adds a material reliability caveat ('not yet verified against a live tenant'). It omits auth/permission requirements and error behavior, which for a tenant-admin-scoped read would be useful.
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 user-facing question and the answer clause, followed by the sibling pointer and the verification caveat. Every sentence carries information; the only slight redundancy is the question framing immediately restated by the 'read whether...' clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool answers, its read-only nature, the sibling relationship, and a reliability caveat — ample for a zero-required-parameter read. With no output schema, it could still say more about the returned shape (a boolean flag plus which fields identify the agent), and it is silent on authentication prerequisites.
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?
All five parameters have full schema descriptions including their environment-variable and workspace-sync defaults, so the schema does the heavy lifting. The description adds no per-parameter meaning beyond what the schema already states, which is the expected baseline at 100% 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?
States a precise verb and resource ('read whether an admin has switched connector consent bypass on for the agent') and frames it as answering a concrete question. It explicitly names cs_set_connector_consent_bypass as the different, mutating step, so the agent can disambiguate without opening either schema.
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 opening question ('do users have to approve this agent's connectors?') gives a clear trigger for selection, and the setter is named as the separate alternative. It stops short of stating exclusions or prerequisites (e.g. that authentication must already be established), so it is clear context rather than a full when/when-not map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status and per-case results of an evaluation run, with a pass/fail summary per test method.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| runId | Yes | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| includeRaw | No | ||
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read operation by describing returned status and results, but says nothing about read-only safety, permissions/auth requirements, pagination, rate limits, or what includeRaw changes.
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?
It is a single compact phrase with no filler, and the result content is front-loaded. It could be a fuller sentence and lacks explicit action framing, but it is appropriately sized for the 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?
The description gives a high-level return shape despite the absence of an output schema, which is useful. However, for a 7-parameter tool with no annotations and no output schema, it omits usage context, auth defaults, and raw-result behavior, leaving meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is moderate (71%), and the description adds no parameter-level meaning. It does not explain runId (the only required parameter), includeRaw, or how botId/clientId/tenantId/workspace/environmentId defaults are resolved.
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 the resource (an evaluation run) and specifies the returned content: status, per-case results, and a pass/fail summary per test method. It distinguishes the per-case/result-summary focus from a sibling like cs_list_evaluation_runs, though it uses a noun phrase rather than an explicit verb.
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 when-to-use guidance, no prerequisites, and no explicit alternatives. The agent must infer that this tool is for fetching a single run's results rather than listing runs or downloading a snapshot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'what does this flow actually do?': one flow's trigger and action names, its connection references, and the whole Power Automate definition when 'includeDefinition' is set. Read-only. Use it before cs_update_flow, and to see why a flow cannot be switched on. For what happened on a particular run, use cs_list_flow_runs and cs_explain_flow_run instead.
| Name | Required | Description | Default |
|---|---|---|---|
| flowId | Yes | Flow (workflow) id; cs_list_flows shows it | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| includeDefinition | No | Include the full definition JSON (large) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must supply the safety profile, and it does declare 'Read-only' plus a size warning that includeDefinition returns the large full definition JSON. It does not mention auth/permission requirements or how tenant/environment defaults are resolved, which are relevant for a 7-parameter tool, so it stops short of full disclosure.
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 plus a routing clause, front-loaded with the core question it answers, with zero filler. The 'use X instead' guidance sits at the end where the reader needs it.
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?
There is no output schema, and the description compensates by naming the return contents (trigger/action names, connection references, optional full definition). Combined with the read-only and size disclosures, an agent has enough 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 100%, so every parameter including includeDefinition's 'large' caveat is already documented in the schema. The description mirrors that for includeDefinition but adds nothing new about flowId or the environment/auth parameters, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('read one flow') and enumerates the exact payload: trigger and action names, connection references, and the full definition when includeDefinition is set. This distinguishes it clearly from cs_list_flows (listing) and the run-oriented 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?
Explicitly prescribes when to use it ('before cs_update_flow', 'to see why a flow cannot be switched on') and names the correct alternatives for a different question ('use cs_list_flow_runs and cs_explain_flow_run instead'). This is a complete routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One run of a cloud flow with its status, timing, trigger and error. Read-only. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | Run id (cs_list_flow_runs) | |
| flowId | Yes | Flow id (cs_list_flows) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description has to carry the load: it does declare read-only and adds a notable caveat that the tool is 'unverified against a live tenant.' It omits what happens on a missing/inaccessible run and whether auth failures surface distinctly, leaving the mutation/error profile partly undocumented.
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 returned resource and fields, then the read-only and auth facts, then the reliability caveat. Compact with no filler, though the fragment style ('Read-only. Uses the Power Automate service...') reads terse rather than explanatory.
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?
No output schema exists, and the description compensates by naming the fields returned. Auth scope and the live-tenant caveat cover the main unknowns for a single-record read. Only error/not-found behavior is left unaddressed.
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 (runId, flowId, connection/auth defaults) is already documented in the schema, including where ids come from. The description adds no parameter-level semantics of its own, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (one flow run) and enumerates the payload an agent gets back: status, timing, trigger and error. 'One run' implicitly contrasts with cs_list_flow_runs, but no sibling is named explicitly, so it stops 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 auth precondition is stated ('Uses the Power Automate service, cs_login scope flow'), which is genuine usage context. However, it never says when to pick this over cs_list_flow_runs, cs_explain_flow_run, cs_compare_flow_runs or cs_analyze_flow_health — the closest siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full catalogue entry for one agent: metadata, element types, availability and deployment state, and whether it is blocked. The raw body is returned alongside the mapped fields, because the detail resource carries more than the list rows. Read-only (cs_login scope 'graph'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Package id from cs_list_org_agents, e.g. P_19ae1zz1-56bc-505a-3d42-156df75a4xxy | |
| version | No | Graph version for reads. Default v1.0; beta may carry fields v1.0 does not. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares read-only semantics, the required cs_login scope ('graph'), the Agent 365 licence prerequisite, the global-cloud restriction, and candidly flags that it is 'Unverified against a live tenant.' It stops short of describing failure modes or behavior under missing licence/permissions, keeping it from a 5.
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 what the tool returns, then constraints, then the caveat — three tight sentences with no filler. The clause explaining the raw body ('the detail resource carries more than the list rows') earns its place as rationale.
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 no output schema, the description compensates by enumerating the returned content and noting the raw body, which is exactly what an agent needs. Prerequisites and scope are covered; only error/permission-failure behavior is left implicit.
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%, including defaults and fallback chains for clientId/tenantId/workspace and the enum for version, so the baseline is 3. The description adds no parameter detail of its own, but neither does it waste words; the schema fully carries this dimension.
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 ('Full catalogue entry for one agent') and enumerates the payload (metadata, element types, availability/deployment state, blocked flag, raw body). This is clearly distinct from the sibling list/bulk tools like cs_list_org_agents and cs_block_org_agent.
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 (fetch detail for a single agent when the list rows are insufficient) and gives real constraints — 'Needs a Microsoft Agent 365 licence and is global-cloud only.' But it never explicitly says when to reach for this versus cs_list_org_agents or cs_review_agent, so the routing guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show one evaluation test set of an agent with its test cases. Read-only. testSetId comes from cs_list_test_sets. Runs 'pac copilot-studio get-maker-evaluation-test-set' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| botId | Yes | Agent id (GUID) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| testSetId | Yes | Test set id (cs_list_test_sets) | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral load; it usefully declares 'Read-only' and names the underlying pac command and auth profile behavior. However, it says nothing about error behavior, permissions, or whether the run blocks, so the disclosure is partial.
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 tight sentences: purpose, safety trait, parameter provenance, and execution context, all front-loaded with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch with full schema coverage and no output schema, the description covers purpose, safety, parameter sourcing, and execution mechanism. It could say more about the shape of the returned test cases, but nothing essential to invoking it 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 is 3; the description adds provenance for the required testSetId ('comes from cs_list_test_sets'), which helps an agent source the value rather than guess. It adds no semantics for botId or the optional pac flags 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 verb ('Show') and resource ('one evaluation test set of an agent with its test cases'), which clearly separates it from cs_list_test_sets and the other evaluation tools. An agent knows exactly what it retrieves without opening the schema.
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?
Names the sibling that produces the required testSetId (cs_list_test_sets) and notes it runs under the active pac auth profile, giving clear context for when to call it. It stops short of explicit when-not conditions or alternatives for retrieving test sets by other means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full turn list of one session: who said what, in order, with the topic and tool attributed to each turn where the transcript records them. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| transcriptId | Yes | conversationtranscriptid, from cs_list_transcripts | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it declares 'Read-only' and discloses that attribution is only present 'where the transcript records them,' which usefully signals optional fields. However, it says nothing about auth requirements (the clientId/tenantId/botId params imply MSAL auth), pagination, or size limits on a potentially long transcript.
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 with the payload content front-loaded and the read-only qualifier trailing; nothing is redundant or padded.
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?
There is no output schema, so the description must describe returns, and it does — turn ordering, speakers, and per-turn topic/tool attribution. The main gap is pagination/truncation behavior for long transcripts, which matters for a tool returning a full turn list.
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 six parameters are documented in the schema, including defaults and the transcriptId source. The description adds return-shape context but no parameter 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?
States a concrete verb and resource ('the full turn list of one session') and even previews the payload shape (speaker, order, topic/tool attribution). It implicitly separates itself from cs_list_transcripts and cs_summarize_transcripts by emphasizing 'full turn list,' but it never names an alternative explicitly.
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 no when-to-use or when-not-to-use guidance. The routing hint ('from cs_list_transcripts') lives in the transcriptId schema description, not the description itself, so an agent gets no explicit instruction about when to reach for this versus cs_summarize_transcripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain how to do one part of Copilot Studio agent development with this server's tools: 'getting-started' (clone or create an agent and take it to a published, tested state), 'instructions' (write the agent's instructions, with AI Builder or by hand), 'knowledge' (add public site, SharePoint, Graph connector or file knowledge), 'tools' (find a connector operation, add the tool, bind its connection), 'topics' (deterministic conversations: triggers and the node types), 'flows' (build a cloud flow, bind its connections, run it, and work out why a run failed), 'evaluations' (test sets, runs and results, plus local conversation tests), 'publish-and-test' (publish the agent and chat with it), 'drift' (changes made in the portal since the last sync, and how to merge them), 'transcripts' (what real users asked, how those sessions ended, and turning the failures into a test set), 'solutions' (pull a solution, redeploy it elsewhere, compare environments), 'administration' (tenant administration with a separate admin account, and backing the tenant configuration up to files), 'troubleshooting' (the errors this server can return, and what each one means). Read the relevant topic when you do not know which tools a job needs or what order they go in; it names the tool for each step and the manual portal steps that cannot be automated. It only explains - it changes nothing and does no work, so when the user asked for something to be built, written or run, call the tool that does it rather than this one. Also returns next steps for the workspace at hand.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Default getting-started | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool only explains, changes nothing, does no work, and returns next steps for the workspace, which is adequate for a read-only guide. It does not discuss permissions, authentication, rate limits, or error behavior, but those are less central for this kind of 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 long, but for a guide tool the enumeration of all 13 topics is useful and each entry earns its place. The purpose and usage caveat are front-loaded before the topic list, and there is no redundant or empty filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and the lack of annotations and output schema, the description is complete enough for correct invocation: it states the tool's purpose, lists all topic scopes, explains when to use it versus action tools, clarifies that it changes nothing, and notes that it returns next steps. No output schema is needed because the description explains the return context.
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, but the description adds real meaning beyond the enum labels by explaining what each topic covers, such as 'getting-started (clone or create an agent...)' and 'drift (changes made in the portal since the last sync...)'. The workspace parameter is left to the schema, which already describes its default, so this is a modest but genuine improvement over the schema alone.
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 ('Explain') and resource ('how to do one part of Copilot Studio agent development with this server's tools'), and it distinguishes itself from every sibling action tool by stating it only explains and changes nothing. An agent can immediately tell that cs_guide is a reference/help tool rather than a tool that performs work.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to read the relevant topic when you do not know which tools a job needs or what order they go in, and it explicitly excludes cases where the user asked for something to be built, written, or run, directing the agent to call the tool that does it instead. This is a clear when-to-use and when-not-to-use statement with a named alternative class.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution import of a packed agent (from cs_pack) into an environment. Mutates the environment: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| environment | No | ||
| forceOverwrite | No | ||
| publishChanges | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the two most important traits: the tool mutates a live environment and requires confirm: true. That is genuine value. It does not cover failure/rollback behavior, whether an existing solution is overwritten by default, or the side effects of publishChanges, so the disclosure is partial.
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 short sentences with the action front-loaded and the mutation/confirm constraint placed second, which is the right priority order. It is efficient with no filler, though the telegraphic phrasing leaves the sentences doing double duty.
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 five-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits what happens to a pre-existing solution, the effect of forceOverwrite and publishChanges, and any indication of the result the agent should expect.
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% — of five parameters, only confirm is documented in the schema. The description reinforces confirm and hints that path comes from cs_pack output, but environment, forceOverwrite, and publishChanges are unexplained in both places, leaving the majority of the input surface undocumented.
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: 'pac solution import of a packed agent (from cs_pack) into an environment.' It also identifies the upstream sibling (cs_pack) that produces the input, which helps distinguish it from cs_deploy_solution or cs_push. It stops short of explicitly contrasting itself with those sibling deployment 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 reference to 'a packed agent (from cs_pack)' implies the prerequisite that packing must happen first, and the mutation warning implies this is a live-environment action rather than a dry run. However, it never states when to prefer this over cs_deploy_solution, cs_push, or cs_sync_solution, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether this machine is ready to work: the pac CLI and .NET, which pac auth profile is active, which cloud resources have a usable token, the environment variables, the write policy in force, and the agent workspace it found, ending with the next steps for that workspace. Read-only. Call it once at the start of a session, and again when a tool fails and you need to know whether the CLI, the credentials or the workspace is the reason. It reports the state of the machine and nothing else: when the user asked for something specific - an agent, a flow, a solution, an environment, instructions - call the tool for that thing instead. cs_create_agent scaffolds or creates an agent; cs_guide explains a task.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does state 'Read-only' plus the exact diagnostic categories it returns, including the trailing 'next steps'. It also bounds the behavior ('reports the state of the machine and nothing else'). It stops short of describing failure/error behavior or whether repeated calls are cheap, so it is strong but not exhaustive.
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 content is front-loaded and every clause earns its place by naming either an inspected resource or a routing condition. It is written as a dense run-on sentence with three back-to-back imperatives, which costs some readability but not much substance.
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?
There is no output schema, so the description compensates by enumerating the reported state categories and the 'next steps' ending. Combined with the read-only framing, call triggers, exclusions and sibling routing, an agent has everything needed to invoke this correctly and interpret 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% for the single optional 'workspace' parameter, and the description never mentions it (no defaults, no resolution order, no interaction with CPS_WORKSPACE). Baseline 3 is the correct ceiling when the schema already documents the only 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 opens with a specific verb-plus-scope statement ('Check whether this machine is ready to work') and then enumerates exactly what state it inspects: pac CLI/.NET, active auth profile, cloud resources with usable tokens, environment variables, write policy, and the discovered workspace. This is far beyond restating the name and lets an agent distinguish it from status-like siblings such as cs_status or cs_login_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?
It gives explicit triggers ('once at the start of a session', 'again when a tool fails and you need to know whether the CLI, the credentials or the workspace is the reason') and an explicit when-not ('when the user asked for something specific... call the tool for that thing instead'). It even routes to named alternatives, cs_create_agent and cs_guide, leaving essentially nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scaffold a Dataverse solution project (.cdsproj) on disk for source-controlled solution development. Runs 'pac solution init' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| publisherName | Yes | Publisher name | |
| timeoutSeconds | No | Default 600 | |
| outputDirectory | No | Output directory (default: cwd) | |
| publisherPrefix | Yes | Publisher customization prefix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it discloses the underlying 'pac solution init' command and that it uses the active auth profile, which is genuinely useful. However, it omits prerequisites (pac installed/authenticated), overwrite behavior when the directory exists, and any side effects on disk.
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 action and artifact, with zero filler. The mechanism sentence adds value rather than restating the name.
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?
A disk-mutating scaffold tool with no annotations and no output schema: the description says what it creates and how, but leaves success output, idempotency/overwrite behavior, and prerequisites unstated. Adequate but with clear gaps for a tool that writes to the filesystem.
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 7 parameters in detail (cwd, profile, background, timeout, outputDirectory, publisher fields). The description adds only that auth uses the active profile, which the schema already covers. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (scaffold) and resource (Dataverse solution project/.cdsproj) and even names the underlying command. The 'on disk for source-controlled solution development' scoping distinguishes it conceptually from cs_create_solution, though it never names that sibling explicitly.
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?
'For source-controlled solution development' implies the use case, but there is no explicit routing against the many solution siblings (cs_create_solution, cs_clone_solution, cs_pull_solution). The agent must infer which solution-creating tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The state of a job started with background: true - running, succeeded or failed - with the phases it has reached and, once finished, the result the tool would have returned. Read-only. Jobs live in the server process, so a restart loses them; pass recordFile to read the copy the job wrote to disk instead.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | No | Omit to list every job this server knows about | |
| recordFile | No | Read a job record from disk (e.g. <targetDir>/pull-job.json) when the server has been restarted since |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose real behavioral traits: it is read-only, jobs are process-local and lost on restart, and recordFile reads the on-disk copy. That ephemerality/lifetime disclosure is exactly the kind of context structured fields cannot convey. It stops short of auth requirements, blocking behavior, or retention of the disk record.
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 compact sentences, front-loaded with what the tool returns, then the safety profile, then the persistence caveat. The first sentence's dash-heavy construction is slightly dense, but every clause carries information and nothing is padding.
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 no output schema, the description correctly compensates by describing the return content (reached phases and the eventual result), and it covers the restart failure mode plus the disk fallback. An agent has enough to call and interpret it, though polling behavior and the listing-all-jobs case are left to 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?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the recordFile scenario ('when the server has been restarted since') but largely restates what the schema already says, and it does not mention that omitting jobId lists all jobs — that behavior is documented only 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 states a specific resource and scope: the state of a job started with background: true, enumerating the possible states (running, succeeded, failed) and what the response contains (phases, final result). It is clear what the tool returns, but it never differentiates itself from crowded siblings like cs_status, cs_list_flow_runs, or cs_get_flow_run, so an agent must infer from the name alone which status tool to pick.
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?
Usage is only implied: you call this after starting a job with background: true. The one piece of explicit routing advice is for a parameter, not the tool — 'pass recordFile ... instead' when the server has restarted. There is no stated guidance on when to prefer this over cs_status or other run-inspection tools, and no polling cadence guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Copilot Studio agents in an environment. via 'pac' uses 'pac copilot list' (needs a pac auth profile); via 'dataverse' queries the bots table with the MSAL token. Default auto: pac when available, else dataverse.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| ownerOnly | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| dataverseUrl | No | ||
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose non-obvious behavior: two distinct execution backends, the auth prerequisite for the pac path ('needs a pac auth profile'), the MSAL-token path for dataverse, and the auto-fallback rule. It omits read-only confirmation, failure behavior, and pagination/result-size traits, so it is informative but not complete.
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 dense sentences, front-loaded with the purpose followed by mechanism and default resolution; every sentence carries information. The parenthetical backend notes are terse but readable, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, zero-annotation tool with no output schema, the description covers the primary behavioral mode but says nothing about what is returned (fields, count, pagination) or how the unlisted parameters (ownerOnly, dataverseUrl) affect results. It is adequate to start a call but leaves the agent to discover output shape empirically.
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 only 57%, and the description meaningfully explains the single enum parameter ('via') by mapping each value to its backend behavior — value the schema's bare enum does not provide. It adds nothing for ownerOnly or dataverseUrl, which are undocumented in both the schema and the description, so it only partially compensates for the coverage gap.
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 ('List Copilot Studio agents in an environment') and even names the underlying mechanisms, so the core purpose is unambiguous. It does not, however, distinguish itself from the close sibling cs_list_org_agents, leaving the agent to guess which listing scope applies.
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 real decision logic for the 'via' modes (pac when available, else dataverse) and notes the pac auth-profile prerequisite. It stops short of when-to-use guidance against alternatives such as cs_list_org_agents or cs_env_list, so usage is only implied at the tool-selection level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The pac authentication profiles on this machine, which one is active, and which account each belongs to. Use it to find the name of the admin profile to pass as 'profile' to the admin tools. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description explicitly labels the tool 'Read-only' and discloses what it reports: available profiles, the active profile, and account ownership. It does not describe output structure or error behavior, but for a zero-parameter listing tool the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short statements convey output content, use case, and read-only nature with no filler. The first sentence is a grammatical fragment ('The pac authentication profiles...'), but it remains compact and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter, read-only list tool with no output schema, the description covers what the call returns, why to call it, and its safety. It could include exact output formatting, but the agent has enough information to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% because there is nothing to document. The description's mention of 'profile' is about a value to pass to other admin tools, not an input to this tool. Baseline 4 for zero params 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 specifies the resource (PAC auth profiles on this machine), the output aspects (active profile and owning account), and the intended role (finding the admin profile name). It is distinguishable from sibling tools like cs_select_auth_profile and cs_delete_auth_profile, though the opening is a noun phrase rather than an explicit verb like 'Lists'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to use the tool to find the admin profile name to pass as 'profile' to admin tools. It does not name alternative tools or explicitly state when not to use it, but the use case is clear enough to guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac connection list: connections that exist in an environment (id, connector, owner). Use the ids to map connection references in a deployment settings file before cs_deploy_solution.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | No | Environment id or URL. Defaults to the active pac auth profile. |
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 payload shape (id, connector, owner) and the intended downstream use, but says nothing about permissions/auth requirements, pagination, whether the environment defaults to the active profile, or whether results are scoped or complete. Adequate for a read-only list, but not rich.
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 compact sentences: the operation and its return fields are front-loaded, followed immediately by the actionable workflow hint. No filler, no restatement of the tool name.
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 no output schema, the description compensates by naming the returned fields, and the single parameter is fully documented in the schema. For a simple environment-scoped list call the description is nearly sufficient; only the absence of any note on default environment behavior or result volume keeps it from being 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?
Only one parameter and schema description coverage is 100%, so the schema already explains that 'environment' takes an id or URL and defaults to the active pac auth profile. The description's 'in an environment' adds no syntax or format detail beyond that. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('list connections that exist in an environment') and even enumerates the returned fields (id, connector, owner), so the agent knows exactly what this returns. It does not explicitly distinguish itself from the nearby cs_list_connectors (connector types) or cs_create_connection, but the 'exist in an environment' phrasing implies instance-level connections rather than catalog entries.
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?
Gives a concrete usage context and workflow: 'Use the ids to map connection references in a deployment settings file before cs_deploy_solution.' That tells the agent when this tool belongs in a sequence. It stops short of stating when not to use it or naming the closest alternative (cs_list_connectors) for disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The environment's connector registry (the same list the portal's Add a tool shows): Microsoft-published and custom connectors, with an mcpLikely flag for MCP servers. Cached under .cs-catalog//connectors.json for offline use; with search and no sign-in, falls back to the offline seed of public connectors.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| mcpOnly | No | ||
| offline | No | Use cache or seed only | |
| refresh | No | Fetch again even if cached | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| customOnly | No | ||
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
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 usefully discloses caching behavior under .cs-catalog/<environment>/connectors.json, offline fallback to the public seed, and the data source ('same list the portal's Add a tool shows'). But it omits authentication prerequisites (beyond the sign-in fallback hint), rate limits, pagination, and error 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 essentially one compact sentence with semicolons, front-loading the core purpose and then adding cache/offline behavior. There is no filler, though the dense packaging could be slightly split for readability.
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 9 parameters with 0 required and no output schema, the description could do more to explain the shape of the returned connector list (e.g., fields beyond mcpLikely) and the authentication context. It covers the data source and offline behavior but leaves gaps around parameter interactions and return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, so the schema documents most parameters. The description adds meaning to the search and offline parameters by explaining the offline fallback and cache usage, and notes the mcpLikely output field. It does not explain several other parameters (mcpOnly, customOnly, refresh, clientId, tenantId, workspace, environmentId) beyond what the schema already says.
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+resource ('list connectors') and clarifies the scope (Microsoft-published and custom connectors, with an mcpLikely flag). It distinguishes from generic lists by referencing the portal's 'Add a tool' view, but it does not explicitly contrast with nearby siblings like cs_describe_connector or cs_list_connections.
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?
Usage is implied: the tool lists connectors in an environment. The description notes offline caching and a fallback to the public connector seed when searching without sign-in, which hints at when the tool works in disconnected scenarios. However, it never states when to use this versus alternatives such as cs_describe_connector for details or cs_list_connections for connections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Power Platform environments the signed-in user can access (BAP API), with Dataverse URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the backing API (BAP) and that results include Dataverse URLs, but says nothing about permission scope failures, pagination, throttling, or what happens when the user has no accessible environments.
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?
A single front-loaded sentence with no filler; scope and return content are stated up front. The '(BAP API)' parenthetical is mildly cryptic but earns its place as source attribution.
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 two-optional-param read tool with no output schema, the description covers what is returned at a high level (environments plus Dataverse URLs) and who it applies to. It omits authentication/permission prerequisites and result volume, which an agent would reasonably want before calling it in a multi-environment workflow.
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 both optional parameters (clientId, tenantId) and their fallback defaults are already fully documented in the schema. The description adds no parameter-level meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List Power Platform environments') with a clear scope qualifier ('the signed-in user can access'), which separates it from the admin-scoped sibling cs_admin_list_environments. It does not explicitly name any sibling, so the differentiation is inferential rather than stated.
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 when-to-use, when-not-to-use, or alternative routing. Siblings such as cs_admin_list_environments, cs_env_list, and cs_env_select also deal with environments, and the description gives no rule for choosing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Previous evaluation runs for the agent.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only listing operation, nor does it mention pagination, ordering, result limits, or what happens when no runs exist.
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 single sentence is concise with no wasted words, but it is a sentence fragment and does not front-load an explicit action verb such as 'List'.
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 no output schema and no annotations, the description should do more to explain the listing behavior and return shape. It states only that previous evaluation runs exist for the agent, leaving key details about the result set unstated.
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 optional parameters with defaults are documented in the schema. The description adds no additional parameter meaning beyond that baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('evaluation runs') and scope ('for the agent'), and the tool name implies listing. However, it uses a noun phrase rather than a clear verb and does not distinguish this from sibling tools like cs_get_evaluation_run.
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 implies the tool is for viewing previous evaluation runs, but gives no explicit guidance on when to use it instead of cs_run_evaluation or cs_get_evaluation_run. There are no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'when did this flow last run, and did it work?': the run history of one cloud flow, most recent first, with status, start and end time, duration and the error of a failed run. Read-only. Use it to find the run you care about, then cs_explain_flow_run on that run to learn why it failed. Uses the Power Automate service, which is a separate sign-in from Dataverse (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum runs to return | |
| flowId | Yes | Flow id (cs_list_flows) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the load and does well: it declares read-only, discloses that this uses a separate Power Automate sign-in from Dataverse (cs_login scope 'flow'), and honestly flags 'Unverified against a live tenant.' It stops short of describing result limits or error behavior, which is the remaining 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?
Front-loaded with the user question it answers, then the shape of the result, then the sibling handoff and auth caveats. Efficient, though the auth/CPS-environment caveat sentence is dense and pushes length close to the limit.
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?
There is no output schema, so describing the returned fields (status, start/end, duration, failed-run error) is essential and present. Combined with the auth-domain note and sibling routing, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all six parameters including flowId's cross-reference to cs_list_flows. The description adds no parameter-level detail beyond the implicit mention of run fields, 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?
States a specific verb+resource (run history of one cloud flow) with ordering and the exact fields returned (status, start/end time, duration, error). It is cleanly distinguished from cs_get_flow_run and cs_explain_flow_run, which appear as 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?
Frames the use case as answering 'when did this flow last run, and did it work?' and then names the downstream alternative explicitly: 'find the run you care about, then cs_explain_flow_run on that run to learn why it failed.' The when-to-use and the handoff are both explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'which flows are there?': every cloud flow in the environment with its state, owner and last change, so you can see what the agent's flow tools can call and what a solution import left switched off. Read-only. This is the inventory only. For one flow's contents use cs_get_flow; for its execution history use cs_list_flow_runs; for the cause of a failure use cs_explain_flow_run.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum rows | |
| search | No | Only flows whose name contains this text | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| includeManaged | No | Default true; false lists only unmanaged flows |
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 explicitly declares 'Read-only' and 'inventory only', and describes the returned fields (state, owner, last change). However, it does not mention authentication requirements, pagination behavior, or rate limits, leaving some behavioral gaps for an 8-parameter 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?
Four short sentences, front-loaded with the question it answers and the scope, then the read-only safety trait, then explicit routing to alternatives. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe return values; it does so by listing state, owner, and last change. It also covers scope, read-only behavior, and sibling routing. Given the rich schema descriptions for all parameters, the definition is complete enough for correct invocation.
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 eight parameters are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('list every cloud flow in the environment') and specifies scope. It explicitly distinguishes itself from siblings by naming cs_get_flow, cs_list_flow_runs, and cs_explain_flow_run with their respective purposes.
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?
Answers the question 'which flows are there?' and provides explicit routing: use cs_get_flow for one flow's contents, cs_list_flow_runs for execution history, and cs_explain_flow_run for failure causes. It also gives concrete use cases, such as seeing what the agent's flow tools can call and what a solution import left switched off.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every agent in the organisation's Microsoft 365 catalogue, across environments, with the things Power Platform cannot see: who the agent is available to, where it is deployed, and whether an admin has blocked it. Defaults to agents built in Copilot Studio; pass platform: 'all' to include the Agent Builder and acquired apps. Read-only. Uses Microsoft Graph, a separate sign-in from Dataverse (cs_login scope 'graph'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum packages per page | |
| host | No | Only agents surfaced in this host | |
| filter | No | Extra raw OData $filter, combined with the options above | |
| version | No | Graph version for reads. Default v1.0; beta may carry fields v1.0 does not. | |
| allPages | No | Follow paging until the catalogue is exhausted (capped) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| platform | No | Build platform. Default 'Copilot Studio'; 'all' does not filter. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| elementType | No | Only packages containing this element type | |
| modifiedSince | No | ISO instant; only packages modified after it, e.g. 2026-01-01T00:00:00Z |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does substantial work: read-only, authenticates via Microsoft Graph with a separate cs_login 'graph' scope, requires a Microsoft Agent 365 licence, is global-cloud only, and is flagged 'Unverified against a live tenant'. It omits volume/paging-throttling behavior (beyond schema notes) and any rate-limit caveat, so it stops short of a 5.
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?
One dense paragraph, front-loaded with the scope and the differentiating return fields before moving to defaults, safety, auth and caveats. Every sentence carries non-redundant information; nothing is padding.
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 11-parameter read tool with no output schema and no annotations, the description supplies scope, defaults, auth path, licensing, cloud constraint and an honesty caveat, plus a sketch of returned fields. It is close to complete; the only real gap is behavior under large catalogues (paging caps, throttling), which the schema mentions only in passing.
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 all 11 parameters — including the four enums — are documented in the schema, so the baseline is 3. The description only restates the platform default/all semantics already present in the schema and adds no syntax or interaction detail (e.g. how top, allPages and filter combine) beyond what structured fields provide.
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 (list) and a precisely scoped resource (every agent in the organisation's Microsoft 365 catalogue, across environments), and lists the distinguishing return fields — availability audience, deployment location, blocked status — that set it apart from the Dataverse-scoped cs_list_agents. The phrase 'the things Power Platform cannot see' implicitly but effectively separates it from its nearest 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?
Gives a concrete default ('Defaults to agents built in Copilot Studio; pass platform: all') and states prerequisites (cs_login graph scope, Agent 365 licence, global cloud only), which is useful context. However, it never says when to choose this over cs_list_agents, cs_get_org_agent, or the cs_admin_list_* family, leaving the routing decision to inference from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the pipelines that can deploy from an environment, or the stages of one pipeline. Read-only. Runs 'pac pipeline list' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| pipeline | No | Pipeline name or id to show its stages | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the important trait: 'Read-only,' plus that it runs 'pac pipeline list' under the active pac auth profile, which tells the agent what credentials and side effects to expect. It stops short of describing output volume, pagination, or failure behavior for a missing pipeline name.
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 short sentences, front-loaded with the resource and its two modes, then the safety trait and execution context. No filler and nothing buried.
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 zero-required-param, read-only list tool with 100% schema coverage, the description covers purpose, the two invocation modes, safety, and the auth context. The remaining gap is that no output schema exists and the return shape is only loosely implied, and it does not connect to cs_deploy_pipeline or cs_job_status for the background path.
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 six parameters are already documented in the schema and the baseline is 3. The description adds only the mapping that supplying a pipeline name switches to stage-listing mode; it adds nothing about cwd, profile, background, environment, or timeoutSeconds beyond what the schema says.
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 (List) and resource (pipelines) plus two distinct scopes: pipelines that can deploy from an environment, or the stages of a single pipeline. Clear enough to act on, but it never names the closely related sibling cs_deploy_pipeline, so the agent must infer the list-vs-deploy relationship on its own.
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 two modes imply when to call it (discover deployable pipelines, or inspect one pipeline's stages), but there is no explicit when-to-use, prerequisite, or 'use X instead' guidance relative to cs_deploy_pipeline or cs_list_environments. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot model list: AI Builder models (including custom prompts) in the environment, with ids for cs_add_tool type 'prompt'.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| activeOnly | No | ||
| environment | No | Environment id or URL; default active pac profile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose what the listing contains (AI Builder models plus custom prompts, with ids) and the downstream consumer (cs_add_tool). It says nothing about permissions, scope of the environment, pagination, or how search/activeOnly alter results.
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?
A single front-loaded sentence with no filler; the resource being listed comes first and the downstream use follows. Slightly compressed/telegraphic style but nothing wasted.
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 list tool with three parameters, no output schema, and no annotations, the description leaves filtering semantics, scope, and result shape unexplained. An agent cannot tell what search or activeOnly do or what the returned entries look like.
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 only 33% – just 'environment' is documented. The description adds no meaning for 'search' or 'activeOnly', leaving two of three parameters unexplained in both schema and description. It does not compensate for the coverage gap.
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+resource: listing AI Builder models (including custom prompts) in the environment. It also distinguishes itself by tying the output to cs_add_tool type 'prompt', which no sibling list tool does. The 'pac copilot model list' prefix is jargon but doesn't obscure the purpose.
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?
Implies usage by saying the listing yields ids for cs_add_tool type 'prompt', so an agent can infer this is the lookup step before adding a prompt tool. However there is no explicit when-to-use/when-not guidance and no stated alternative for enumerating prompts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution list: solutions in an environment with version and managed flag. Needs a pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | No | Environment id or URL. Defaults to the active pac auth profile. | |
| includeSystem | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds the auth-profile requirement and reports the returned fields, which is genuine context, but says nothing about pagination, filtering behavior, or that it is a non-mutating read beyond the implication of 'list'.
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?
A compact two-clause sentence that front-loads the pac command and purpose, with the prerequisite stated efficiently at the end. No filler, though it is terse to the point of under-specification.
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 tool with no output schema this is minimally adequate: purpose, prerequisite, and partial return content are covered. The undocumented includeSystem parameter and absence of any note on scope or result format leave clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'environment' is documented but 'includeSystem' is undocumented in both schema and description. The description lists output fields (version, managed flag) but never explains what includeSystem controls, so it fails to compensate for the coverage gap.
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 ('list: solutions in an environment') plus the fields returned ('version and managed flag'). This clearly reads as an enumeration tool, distinguishable from mutation siblings like cs_create_solution or cs_delete_solution, though it never names a sibling to contrast with.
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?
'Needs a pac auth profile' states a real prerequisite, which is useful context. However, there is no guidance on when to use this over alternatives such as cs_describe_solution or cs_list_environments, and no exclusion conditions; usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power Platform API: test sets defined for the agent (standard harness).
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It does not state that this is a read-only operation, what permissions are needed, whether results are paginated, or what the return shape looks like. The phrase 'standard harness' is cryptic and adds little actionable 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 a single, compact sentence with no wasted words. It is front-loaded with the resource type. The brevity is appropriate for a list operation, though the sentence borders on under-specification rather than optimal conciseness.
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 five optional parameters, no output schema, and no annotations. The description does not explain what a 'test set' contains, what the response looks like, or how authentication defaults interact. Given the complexity of the Power Platform environment and the number of sibling tools, this description is too thin to fully guide correct invocation.
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 five parameters including their defaults and environment variable fallbacks. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as 'test sets defined for the agent' and adds '(standard harness),' which gives a clear sense of what the tool returns. Combined with the title 'List evaluation test sets,' an agent can determine it lists test sets for an agent. However, it does not explicitly distinguish this from sibling tools like cs_get_test_set or cs_list_evaluation_runs.
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_get_test_set or cs_list_evaluation_runs. It merely states what the resource is, leaving the agent to infer usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sessions people had with the published agent, newest first: when, how many turns, the first thing the user asked, which topics and tools fired, and how the session ended. Read-only. Needs a cached cs_login. Use it to find the session behind a bad answer, then cs_get_transcript for the full turn list.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum sessions (default 100, max 500) | |
| days | No | Only sessions from the last N days | |
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| search | No | Only sessions whose first user message contains this text | |
| outcome | No | Only sessions that ended this way | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the key traits: 'Read-only', the auth prerequisite (cached cs_login), and result ordering ('newest first'). It stops short of pagination/rate-limit or default-scope behavior (e.g. what happens with no filters), which is a minor gap rather than a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the resource and row contents front-loaded, then safety/auth, then sibling routing. No filler and nothing repeated from the 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 nine-parameter, read-only list tool with no output schema, the description supplies the return-content preview, ordering, auth prerequisite, and next-step tool, which is enough to invoke it correctly. Only default filtering scope and pagination nuance are left unstated, and the schema covers the numeric limits.
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 nine parameters are already documented with defaults and the outcome enum. The description's field list (topics, tools fired, how the session ended) loosely corresponds to the search/outcome filters but adds no syntax or semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource ('Sessions people had with the published agent') and enumerates exactly what each row contains (when, turn count, first user ask, topics/tools, ending). It is clearly distinguishable from cs_get_transcript (full turn list) and cs_summarize_transcripts, which it names.
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 an explicit use case ('find the session behind a bad answer') and routes to the correct next tool ('then cs_get_transcript for the full turn list'), plus a prerequisite ('Needs a cached cs_login'). This is when-to-use plus alternative in a single sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acquire a Microsoft Entra token for the cloud tools (evaluations, environments, agents, publish, chat, drift). mode 'interactive' (default) starts a browser sign-in and returns within waitSeconds: status 'ok' when it completed, otherwise status 'pending' with the sign-in URL. If no browser opened, show the user that URL to open on the machine running this server; the page redirects to localhost and the login completes in the background (check cs_login_status or call any cloud tool). mode 'device_code' returns a code to enter at microsoft.com/devicelogin (some tenants block this flow). Not needed for pac commands, which use 'pac auth create'.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Default interactive | |
| scope | No | Which resource to pre-authorise. Default powerplatform (evaluations); 'flow' is the Power Automate service used by the flow-run tools; 'graph' reads the Microsoft 365 agent catalogue and 'graph_write' also blocks and reassigns. Others are acquired silently later when possible. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| openBrowser | No | interactive: try to open the browser from the server (default true). Set false when the server runs where no browser can appear. | |
| waitSeconds | No | interactive: how long to wait for the sign-in before returning 'pending' (default 15; keep it below the client's tool timeout) | |
| dataverseUrl | No | Required when scope is dataverse, e.g. https://org.crm.dynamics.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full behavioral burden and does so well. It explains what interactive mode returns ('ok' or 'pending' with sign-in URL), the localhost redirect and background completion, the fallback of showing the URL to the user, device code behavior and tenant restrictions, and how to check progress via cs_login_status or any cloud 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 front-loaded with purpose and mode behavior, and most sentences add practical value. It is somewhat dense and run-on across parentheticals, but the length is justified by the complexity of an auth flow with two modes and a redirect fallback.
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 and output schema and the eight optional parameters, the description provides the missing context an agent needs: authentication purpose, mode behaviors, return statuses, browser/device-code outcomes, and sibling routing. Nothing critical for correct invocation is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema for mode and waitSeconds — specifying interactive default behavior and the returned status — but leaves details for scope, clientId, tenantId, workspace, openBrowser, and dataverseUrl largely to 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 states a precise verb and resource — 'Acquire a Microsoft Entra token' — and names the cloud tools it unlocks (evaluations, environments, agents, publish, chat, drift). It also explicitly distinguishes itself from pac commands, which use 'pac auth create', so an agent can tell when this tool applies.
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 establishes when to use the tool (cloud operations requiring an Entra token), gives mode-specific guidance for interactive versus device_code flows, and states an exclusion: 'Not needed for pac commands, which use pac auth create.' That covers when, when-not, and the relevant alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'am I signed in?' for the cloud tools: the cached MSAL accounts, and whether a browser or device-code sign-in is still pending, with its URL or code; optionally wait for it to complete. For the separate pac sign-in, cs_auth_who.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Block until the pending sign-in completes (up to 10 minutes) | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses that the tool reads cached MSAL accounts, reports an in-flight browser/device-code sign-in including its URL or code, and can optionally block until completion. The 'am I signed in?' framing conveys a read-only status query. It stops short of stating auth prerequisites or any side effects explicitly.
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 question the tool answers, then the routing note about cs_auth_who. It is dense but every clause (accounts, pending state, URL/code, wait) earns its place. Slightly packed with semicolons, but no wasted 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?
No output schema and no annotations, yet the description compensates by describing what is returned (cached accounts, pending sign-in state and its URL/code). Combined with fully documented optional parameters, an agent has enough to invoke it correctly; only explicit auth/permission context 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 all three parameters (wait, tenantId, workspace) are already documented in the schema, including defaults and the 10-minute wait bound. The description only alludes to the wait behavior and adds no syntax or format detail beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource in the user's own terms ('Answer am I signed in? for the cloud tools') and enumerates exactly what it reports: cached MSAL accounts plus pending browser/device-code sign-in with its URL or code. It also distinguishes itself from the pac sign-in path, so an agent can tell it apart from cs_login, cs_logout, and cs_auth_who without opening a schema.
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 routes the adjacent-but-different case: 'For the separate pac sign-in, cs_auth_who.' This gives a clear alternative for a related question. It does not state when the wait option should be preferred, but the schema documents that flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove cached MSAL accounts for the tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states what is removed (cached MSAL accounts) but says nothing about required auth state, whether active sessions or tokens are affected, or 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 a single front-loaded sentence with no filler or repeated information. It states the verb, resource, and scope immediately without burying the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity logout tool with one optional, fully documented parameter and no output schema, the description is minimally sufficient. However, because there are no annotations and no usage guidance, it omits contextual details an agent might reasonably expect, such as auth prerequisites or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single tenantId parameter is fully documented in the schema, including its default resolution order. The description's 'for the tenant' adds only minor corroboration and no new syntax or format detail, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (remove) and resource (cached MSAL accounts for the tenant), making the tool's core purpose clear and distinct from cs_login and cs_login_status. It does not explicitly distinguish itself from adjacent auth tools such as cs_delete_auth_profile, 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?
There is no statement of when to call this tool, when not to call it, or which sibling to use instead. The 'Sign out' title implies a logout context, but the description itself provides no usage guidance or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the Copilot Studio authoring schema: summarize or resolve a definition (e.g. Question, SearchAndSummarizeContent, KnowledgeSourceConfiguration), search by keyword, or list all kinds.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| depth | No | ||
| search | No | ||
| resolve | No | Return the full resolved JSON instead of a summary | |
| listKinds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It does disclose the key mode distinction ('resolve' returns full resolved JSON vs a summary) and the search/list behaviors, but omits the read-only nature, permissions, or limits one might expect for a lookup 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?
A single front-loaded sentence with a clean enumeration of modes and concrete examples. Efficient, though the mode list is dense and slightly cryptic without a lead-in on parameter mapping.
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 5-parameter tool with no annotations, no output schema, and 20% schema coverage, the description covers the operational modes but leaves 'depth' and the required combination of parameters unexplained, so an agent cannot fully infer invocation semantics.
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% (only 'resolve' documented), so the description must compensate. It loosely maps its modes to name/search/listKinds and echoes the resolve behavior, but 'depth' is left entirely unexplained in both schema and 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?
States a specific verb and resource ('Inspect the Copilot Studio authoring schema') and enumerates three concrete modes (summarize/resolve a definition, search by keyword, list all kinds) with example definitions. No sibling tool does schema lookup, so it is effectively distinct, though the description never explicitly differentiates itself.
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 three modes imply how the tool is used and the examples (Question, SearchAndSummarizeContent, KnowledgeSourceConfiguration) suggest applicable inputs, but there is no explicit when-to-use/when-not guidance or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import translated .resx or .json files back into one or more agents (environment or unpacked solution folder). whatIf previews the merge without writing. Runs 'pac copilot merge-translation' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise). Only some inputs mutate; see the parameter descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| files | Yes | Translation files; glob patterns allowed | |
| whatIf | No | Report what would change without changing anything | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| verbose | No | More diagnostic output | |
| solution | No | Solution unique name | |
| sourceDir | No | Unpacked solution folder to update instead of the environment | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 900 |
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 that this mutates a live environment, that confirm: true is required to actually write, that omitting it yields a dry run, that whatIf is a no-write preview, and that long runs can be backgrounded and polled via cs_job_status. It also names the execution context (pac auth profile) and warns that only some inputs mutate.
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?
Five compact sentences, front-loaded with the purpose and immediately followed by the preview/commit distinction. Every sentence carries operational information, though the staccato, colon-heavy phrasing ('Mutates a live environment: requires confirm: true (a dry run otherwise).') reads slightly telegraphic rather than polished.
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 11-parameter mutation tool with no annotations and no output schema, the description covers the concerns an agent must know before calling: mutation scope, confirmation requirement, dry-run default, background job handling, and auth profile resolution. It does not describe what a successful merge returns or what a dry-run report contains, which is a minor gap given no output schema exists.
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 explains all 11 parameters. The description adds genuine value beyond it by clarifying the confirm/whatIf interaction semantics ('a dry run otherwise') and by flagging that 'Only some inputs mutate; see the parameter descriptions' — telling the agent not to assume every field is a write trigger.
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 first sentence gives a specific verb+resource+scope: 'Import translated .resx or .json files back into one or more agents (environment or unpacked solution folder).' It also names the underlying pac command, so an agent knows exactly what operation runs. It does not explicitly reference the inverse sibling cs_extract_translations, so differentiation is implied by directionality ('back into') rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the preview path ('whatIf previews the merge without writing') and the commit path ('requires confirm: true (a dry run otherwise)'), which is actionable when/when-not guidance. What is missing is any named alternative tool or routing rule (e.g., against cs_extract_translations or cs_pull), leaving the agent to infer that this is the counterpart to extraction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run 'pac <args...>' directly. Read-only commands (list/who/status/help) run immediately; anything else needs confirm: true. 'profile' runs it as another pac auth profile, for example the tenant admin account.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| args | Yes | Arguments after 'pac', e.g. ["env","list"] | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as (cs_init lists them) | |
| timeoutSeconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose a real behavioral trait: read-only commands (list/who/status/help) run immediately while anything else requires confirm: true. The list of exempt commands adds information the schema does not contain. It omits the potential destructiveness of arbitrary pac subcommands and output format, so it is not exhaustive.
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 tight sentences, front-loaded with the escape-hatch framing, then the safety gate, then the profile note. Every clause carries information; there is no filler or repetition of the title.
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 generic 5-parameter escape hatch with no output schema and no annotations, the description covers the safety gate and profile semantics but says nothing about return shape, error behavior, or when to avoid this tool in favor of a dedicated sibling. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 60% schema coverage, the description usefully supplements the schema: it clarifies which commands trigger the confirm gate and explains that 'profile' runs the command as another pac auth profile, with a concrete example (tenant admin account). It adds nothing for cwd or timeoutSeconds, but those are self-descriptive.
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 'pac <args...>' directly — and labels itself an 'escape hatch', which clearly differentiates it from the many dedicated cs_* wrappers. It stops short of naming those siblings or saying to prefer them, so the differentiation is implicit rather than explicit.
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 'escape hatch' framing implies this is a fallback when no dedicated tool exists, and the read-only vs. confirm split gives some when-to-use context. However, with 90+ siblings covering the same pac surface, the description never tells the agent to prefer cs_env_list, cs_login, etc. over this generic tool, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot pack: local-only packaging of the workspace into a Dataverse solution .zip (no sign-in). Also a cheap structural check of the workspace. outputPath must be outside the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| outputPath | No | ||
| solutionName | No | ||
| publisherPrefix | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose two valuable traits — no authentication is required and the operation is local-only — plus a hard constraint on outputPath. However, it says nothing about overwrite behavior, failure modes, or what the 'structural check' actually reports.
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 compact sentences with the core purpose front-loaded and zero filler. The "pac copilot pack:" prefix is slightly redundant with the tool name, but otherwise the structure is 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 4-parameter tool with no annotations, no output schema, and 25% schema coverage, the description covers purpose, auth profile, and one constraint, but leaves half the parameters and any return/failure behavior unexplained. Adequate but with visible gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (workspace is the sole documented parameter), so the description must compensate. It adds a real constraint for outputPath ("must be outside the workspace"), but solutionName and publisherPrefix remain undocumented in both the schema and the 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?
States a specific verb+resource: packaging the workspace into a Dataverse solution .zip, plus a secondary role as a structural check. It is clear what the tool does, but it never distinguishes itself from the sibling cs_pack_solution, which an agent could easily confuse it with.
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?
"local-only ... (no sign-in)" and "cheap structural check" imply the context in which this is appropriate, but there is no explicit when-to-use versus cs_pack_solution or cs_check_solution, and no stated prerequisites. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac solution pack: zip an unpacked source folder (after local edits) so it can be deployed.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | ||
| folder | Yes | ||
| packagetype | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It conveys that the operation is a local zip creation, but never says whether the output zip is overwritten if it exists, whether the folder must be a valid unpacked solution, what errors arise on bad input, or what authorization/environment context is required.
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?
A single front-loaded sentence that maps directly to the CLI verb and wastes no words. It is efficient, though the brevity is partly the source of the documentation gaps elsewhere.
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 3-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description should cover packagetype semantics and the folder/zip contract. As written it leaves the agent guessing about a required enum that determines whether the packaged solution is managed or unmanaged.
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 0% across 3 parameters, so the description must compensate. It loosely implies folder = source folder and zip = output archive, but says nothing about packagetype (Managed vs Unmanaged) even though that enum changes the artifact materially.
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: zipping an unpacked source folder into a deployable artifact, and even names the underlying command ('pac solution pack'). It does not however differentiate itself from the sibling cs_pack or explain the relationship to cs_pull / cs_push, so an agent must infer which pack-family tool applies.
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 parenthetical '(after local edits) so it can be deployed' implies the workflow position: run this after modifying an unpacked folder, before deployment. There are no explicit when-not conditions and no named alternatives (cs_pack, cs_push, cs_deploy_solution) to disambiguate a large pack/pull/push sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make the agent's current draft visible to real users on its channels - the tool for 'go live', 'release it' and 'make my changes live'. It publishes what is already in Copilot Studio, so send local edits up with cs_push first. via 'pac' runs 'pac copilot publish'; via 'dataverse' calls the PvaPublish action with the MSAL token and polls until publishedon changes. Requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | ||
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| background | No | Run in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled. | |
| dataverseUrl | No | ||
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| timeoutSeconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the real-user-visible side effect, the confirm:true gating, the dry-run-without-confirm behavior, and the two execution paths (pac CLI vs PvaPublish via MSAL token polling until publishedon changes). It does not discuss reversibility, permissions/roles, or failure modes, so it falls short of a 5.
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 purpose, then prerequisite, then execution mechanics; every sentence carries information. The implementation detail ('PvaPublish action', 'publishedon changes') is slightly lower-level than an agent strictly needs, but it is compact and not padded.
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 10-parameter mutation tool with no annotations and no output schema, the description covers the critical gaps: the confirm gate, the prerequisite step, and the long-running/background implication (reinforced by the background param's jobId/cs_job_status note in the schema). It stops short of describing the success result or error conditions.
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 70% and the 'via' enum has no schema description, so the description earns real credit by explaining what each value does ('pac copilot publish' vs the PvaPublish action with polling). It also restates the confirm:true requirement, reinforcing the one parameter that most affects behavior.
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 object ('make the agent's current draft visible to real users on its channels') and gives synonym triggers ('go live', 'release it'). It also distinguishes itself from the closest sibling by clarifying it publishes what is already in Copilot Studio rather than uploading local edits, which is exactly the boundary an agent needs against cs_push.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use context plus an explicit prerequisite/alternative: 'send local edits up with cs_push first'. It does not state a when-not condition or contrast with other publish-adjacent siblings such as cs_publish_customizations or cs_deploy_pipeline, but the sequencing guidance is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish every unpublished customization in the environment (the 'Publish all customizations' button). Runs 'pac solution publish' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 3600 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the key behavioral traits: it mutates a live environment and is gated behind confirm: true with a dry run otherwise. However, it says nothing about permissions required, whether the publish is reversible, how long it takes, or that concurrent unpublisheable changes could be affected.
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 tight sentences, front-loaded with what gets published, then the mechanism, then the safety gate. Every clause carries information and none is redundant.
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 eight-parameter, zero-required tool with no annotations and no output schema, the description covers the critical unknowns: that it is a live mutation and how to actually trigger it. Minor gaps remain around result reporting and async/background interaction, which the schema only partially covers.
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 eight parameters, making 3 the baseline. The description adds only marginal meaning, restating the confirm gating and the active-profile default that the schema already spells out.
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 with an explicit scope: 'Publish every unpublished customization in the environment,' reinforced by the quoted UI button label. The 'all' scope implicitly separates it from the sibling cs_publish, but it never names that alternative, so differentiation is left to inference.
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 a prerequisite (confirm: true or you get a dry run) and context (runs under the active pac auth profile), which tells the agent when it will actually take effect. It never says when to prefer this over cs_publish or which situations call for publishing everything, so alternatives remain unaddressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot pull: three-way merge of server changes into the local workspace (also downloads knowledge files). Run before editing and before pushing. Records a sync stamp (.mcs/cs-sync.json) so cs_check_drift can tell later portal changes from yours; commit the workspace afterwards to keep a reviewable history.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this is a merge/mutation of the local workspace, that knowledge files get downloaded, and that it writes a sync stamp at .mcs/cs-sync.json, plus a recommended commit to preserve history. It omits auth prerequisites and conflict/failure behavior, which keeps it from a 5.
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 action, then layered sequencing and side-effect notes; nearly every clause carries information. It is dense but not padded, though the parenthetical and stamp path add a little length.
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 no-annotation, no-output-schema, single-param tool, the description covers purpose, ordering, side effects, and the sync-stamp consequence, which is enough to invoke it correctly. Only failure modes and auth/permission expectations are left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single workspace parameter is fully documented there, including the CPS_WORKSPACE default. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('three-way merge of server changes into the local workspace') and adds the concrete side-purpose of downloading knowledge files. An agent can distinguish it from cs_push and related sync siblings without opening any schema.
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?
Gives explicit sequencing guidance ('Run before editing and before pushing') and ties the tool to cs_check_drift via the sync stamp, which tells the agent why and when it matters. It stops short of naming an explicit when-not-to-use or a direct alternative, so it lands at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the solution (unmanaged and optionally managed), unpack it to /src, write /solution.json, generate deployment-settings.json (connection references + environment variables to map), and clone every agent in the solution into /agents/ as a sync-connected workspace. This is the input for cs_deploy_solution.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Solution unique name | |
| targetDir | Yes | ||
| background | No | Run in the background and return a jobId immediately. Use this when the export is large enough that the MCP client times the call out; poll with cs_job_status. | |
| cloneAgents | No | Default true | |
| environment | No | Environment id or URL. Defaults to the active pac auth profile. | |
| packagetype | No | Default Both: exports both zips, unpacks both |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses significant side effects: unpacking into <targetDir>/src, writing solution.json, generating deployment-settings.json, and cloning agents as sync-connected workspaces. It still omits prerequisites such as authentication needs, overwrite behavior on existing targetDir contents, and error or rate-limit 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 dense but front-loaded, beginning with the core action and then listing the side effects in a logical order. It is one very long sentence plus a short closing sentence, so readability could be improved, but every clause is informative and nothing appears wasted.
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 six-parameter tool with no output schema, the description explains the key outputs and its downstream relationship to cs_deploy_solution well enough to call it correctly. It lacks guidance on when to prefer it over similar siblings and omits auth/overwrite prerequisites, so it is 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 coverage is high at 83%, so the baseline is 3. The description adds real meaning beyond the schema by explaining the targetDir layout and the generated deployment-settings.json contents, though it leaves some parameters such as background and environment largely to their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Export the solution') and enumerates the exact local artifacts it produces, so the agent knows what the tool does. It also distinguishes itself from cs_deploy_solution by calling itself the input for that tool. However, it does not differentiate itself from nearby siblings such as cs_pull, cs_clone_solution, or cs_sync_solution.
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 by stating 'This is the input for cs_deploy_solution,' which tells the agent when this tool fits in a workflow. It does not provide exclusions or compare itself directly to alternative pull/clone/sync tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send local file changes up into the agent's draft in Copilot Studio - topics, knowledge files, flows, connection references - so the draft matches your workspace (pac copilot push). This is the tool for 'upload', 'send my changes up' and 'sync my edits'. It only moves files into the draft; cs_publish is the separate step afterwards. Validates YAML first and blocks on errors unless force. The dry run also reports components changed in Copilot Studio since the last sync (quick drift check, needs a cached cs_login); when one of those also changed locally the push is blocked unless force. Changes the agent in Copilot Studio: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Push even if validation reports errors or portal changes conflict with local edits | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so: it discloses the draft-only scope, YAML validation gating, force override behavior, the drift check in dry run and its cs_login prerequisite, and the confirm: true requirement. These are real operational traits, not restatements of the name.
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-loads the core action and the publish distinction, then layers on validation, drift, and confirm behavior. It is dense but each sentence carries operational content; it runs slightly long for a 3-parameter 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?
With no output schema and no annotations, the description does the heavy lifting on mutation semantics, gating, and side effects, and hints at dry-run output. It stops short of describing the full result payload, but no critical calling information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented in the schema. The description's notes on force (override validation/conflict) and confirm (dry run without it) largely mirror the schema text rather than adding new syntax or edge-case meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (push/send up) and resource (local file changes into the agent's draft), and enumerates the artifact types covered (topics, knowledge files, flows, connection references). It explicitly distinguishes itself from cs_publish as the separate next step.
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?
Gives the natural-language triggers an agent will encounter ('upload', 'send my changes up', 'sync my edits') and names the alternative cs_publish with the condition that selects it. Zero inference required to route between push and publish.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put an agent in quarantine (users cannot talk to it) or release it. Admin operation. Runs 'pac copilot quarantine' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| botId | Yes | Agent id (GUID) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| quarantine | No | true to quarantine (default), false to release | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this mutates a live environment, that confirm:true is required to avoid a dry run, that it runs 'pac copilot quarantine' under the active auth profile, and the user-visible effect of quarantine. It omits return shape and any pagination/rate-limit notes, but covers the critical destructive-operation traits.
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 tight sentences with the operation, semantics, and the confirm safety gate front-loaded. No filler, though sentence 3 (the underlying pac command) is arguably internal implementation detail rather than agent-facing guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive admin tool with no output schema and no annotations, the description is solid: it covers the mutation effect, the confirm requirement, and the auth profile context. It could be more complete by naming the sibling alternative or hinting at the response, but nothing essential to calling it correctly 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 schema already documents all 8 parameters. The description reinforces the confirm gate and the quarantine/release direction, but adds no format or syntax detail beyond what the schema provides, making the baseline 3 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 pair (quarantine/release) and resource (agent), and explains what quarantine means behaviorally ("users cannot talk to it"). It does not explicitly differentiate itself from the similar sibling cs_block_org_agent, 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?
Gives useful context ("Admin operation", requires confirm:true or it is a dry run), which implies when the tool will actually take effect. However, it never names an alternative or states when to prefer this tool over cs_block_org_agent or cs_delete_agent, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make another person the owner of a Copilot Studio agent in its Power Platform environment, so they can edit, publish and manage it there. Admin operation. cs_reassign_org_agent is a separate tool for the Microsoft 365 side. Runs 'pac copilot-studio reassign-copilot-agent' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| botId | Yes | Agent id (GUID) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| newOwner | Yes | Entra ID object id of the new owner | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| timeoutSeconds | No | Default 600 |
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 flags that it mutates a live environment, that confirm: true is required or the call is a dry run, that it runs the pac command under the active auth profile, and that it is an admin operation implying elevated credentials.
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 tight sentences, front-loaded with the action and effect, then the sibling disambiguation, the underlying command, and the mutation/dry-run constraint. No filler; each sentence adds decision-relevant 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 an 8-parameter admin mutation with no annotations and no output schema, the description covers the safety-critical traits (live mutation, dry-run default, auth profile, alternative tool). It omits what happens to the previous owner and any downstream effects, a minor gap rather than a blocking one.
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 botId, newOwner, profile, confirm, environment, background etc. are already documented. The description only reinforces the confirm dry-run behavior already present in the schema, adding little parameter syntax or format detail beyond that; 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: transfer ownership of a Copilot Studio agent so the new owner can edit/publish/manage it. It also explicitly distinguishes itself from cs_reassign_org_agent, which handles the Microsoft 365 side, so an agent can pick the right tool without opening schemas.
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?
Clear context is given: this is an admin operation scoped to the Power Platform environment, and the sibling cs_reassign_org_agent covers the M365 side. However, it stops short of stating explicit when-not conditions (e.g. tenants without admin rights) so it does not reach a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand ownership of an agent in the Microsoft 365 agent catalogue to another user, by their Entra object id. Used when the owner leaves the organisation. The agent's owner inside a Power Platform environment is cs_reassign_agent_owner. Changes a live tenant: requires confirm: true. Needs CopilotPackages.ReadWrite.All and runs against Graph beta (cs_login scope 'graph_write'). Needs a Microsoft Agent 365 licence and is global-cloud only. Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Package id from cs_list_org_agents, e.g. P_19ae1zz1-56bc-505a-3d42-156df75a4xxy | |
| userId | Yes | Entra object id of the new owner | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses that the tool mutates a live tenant, requires confirm: true, needs CopilotPackages.ReadWrite.All, runs against Graph beta, requires a Microsoft Agent 365 licence, is global-cloud only, and is unverified against a live tenant.
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 front-loads the core action and then adds only essential qualifications: sibling differentiation, mutation confirmation, auth scope, licence and cloud constraints, and a verification caveat. Every sentence carries unique 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 destructive, tenant-mutating tool with no annotations and no output schema, the description covers all the critical context an agent needs: purpose, alternative, confirmation requirement, permissions, licensing, cloud scope, and implementation maturity.
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 in detail. The description reinforces that userId is an Entra object id but adds no syntax or format detail 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 specific verb ('Hand ownership'), resource ('agent in the Microsoft 365 agent catalogue'), and actor ('to another user, by their Entra object id'). It explicitly distinguishes this tool from the similarly named cs_reassign_agent_owner, which handles the agent owner inside a Power Platform 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 gives the triggering scenario ('Used when the owner leaves the organisation') and names the alternative for a different ownership context ('The agent's owner inside a Power Platform environment is cs_reassign_agent_owner'). It also states the confirm requirement for live changes, leaving no ambiguity about when to use this tool versus its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a topic, knowledge source, tool, trigger, variable or flow from the workspace files (the live agent changes on the next cs_push). For tools, the connection reference is dropped too unless another tool uses it. Reports topics that still redirect to a removed topic. Deletes files: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | Yes | ||
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| pruneConnectionReference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it states this deletes files, that the live agent is only affected on the next cs_push (deferred mutation), that dropping a tool also drops its connection reference unless shared, and that confirm: true is required. It omits auth/permission requirements and reversibility, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core action and the deferred-effect caveat right after. The 'Reports topics that still redirect to a removed topic' sentence is the least essential, but it still conveys return behavior that is otherwise undocumented, so waste is minimal.
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?
No output schema and no annotations exist, so the description must cover behavior and results, and it does address destructiveness, the confirm gate, side effects, and one return detail. It is nearly complete for a destructive workspace-editing tool, missing only permission requirements and a fuller account of 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 coverage is only 40% (kind and name carry no descriptions), so the description must compensate. It partly does: it enumerates the kind values and describes the confirm gate and the connection-reference side effect tied to pruneConnectionReference, but it never explains the pruneConnectionReference parameter's own semantics or the workspace parameter, leaving gaps.
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 gives a specific verb (delete) and an enumerated resource set (topic, knowledge source, tool, trigger, variable, flow) operating on workspace files, so an agent knows exactly what it removes. It does not explicitly distinguish itself from the flow-specific sibling cs_delete_flow, which is the only sibling that overlaps in scope, so it stops 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?
Usage is implied rather than stated: the parenthetical '(the live agent changes on the next cs_push)' signals the intended workflow of editing workspace files and then pushing, and 'requires confirm: true' signals when the operation actually applies. There is no explicit statement of when to prefer this tool over the flow- or connection-specific delete siblings, so it lands at implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Judge whether the agent is any good and say what to improve, as a score out of 10 with a fix for each finding: instructions present and sized, escalation and fallback topics, trigger phrase count and overlap, tool descriptions and name collisions, unbound connections, authentication versus private knowledge, web browsing with internal sources, orchestration off with tools, duplicate names, credentials in YAML, pack-only workspace. Returns a score, findings with fixes, and optional Markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| markdown | No | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| reportPath | No | Write the Markdown report here |
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 evaluation scope and the return shape (score, findings with fixes, optional Markdown), which is useful, but it never states that the operation is read-only/non-mutating or whether it requires specific permissions, leaving the safety profile unstated.
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?
Purpose is front-loaded in the opening clause and the long colon-list enumerates checks that genuinely define the tool's scope. It is dense and run-on rather than padded, losing a point only because the single sprawling sentence would read better as a short structured list.
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 no output schema, the description correctly explains what is returned (score, findings with fixes, optional Markdown), and it covers the parameters' roles. For a read-only review tool with three optional params and no required arguments, this is nearly complete, missing only safety/permission context.
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 67%, between the low and high baselines. The description echoes the optional Markdown output but adds no syntax, format, or defaulting detail for workspace or reportPath beyond what the schema already documents (CPS_WORKSPACE/cwd default, report destination).
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 ('judge whether the agent is any good') and enumerates the concrete dimensions it evaluates, so an agent understands this is a static health review that returns a score plus fixes. It stops short of 5 because it never distinguishes itself from closely named siblings like cs_validate, cs_check_solution, or cs_check_drift.
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 when-to-use or when-not-to-use guidance, no prerequisites, and no reference to alternatives despite a crowded sibling set containing several check/validate tools. The checklist implies the tool's scope but gives the agent no routing signal for choosing it over cs_validate or cs_check_solution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a YAML test file (tests: name, utterance, expect, continueConversation) against the published agent through cs_chat and report pass/fail. expect asserts on wording (contains, containsAny, notContains, regex, minLength, noSignIn) and on what the agent did (usedTool, notUsedTool, usedTopic, notUsedTopic, citedKnowledge), so a test can tell a real tool call from an answer that merely sounds right. Every result reports the observed topic, tool and citations whether or not it asserted on them. The CLI-native complement to portal evaluations. Pass writeExample to create a starter file.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| tests | No | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| transport | No | auto detects the agent's authentication mode via Dataverse; directline for no-auth/manual-auth agents; sdk for Entra SSO agents | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| schemaName | No | ||
| stopOnFail | No | ||
| dataverseUrl | No | ||
| writeExample | No | Path to write an example test file, then return | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| tokenEndpoint | No | Explicit DirectLine token endpoint | |
| conversationId | No | Continue an earlier conversation from cs_chat | |
| directLineSecret | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does well: it explains pass/fail reporting, the expectation types, that every result reports observed topic/tool/citations, and that writeExample writes a file and returns. It does not cover auth requirements or side-effect boundaries in depth, but the core test-execution behavior is clearly 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 dense and front-loaded: the first sentence covers the core action and mechanism, later sentences add assertion and reporting semantics, then the sibling positioning and writeExample hint. Every sentence contributes useful selection or invocation context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 15-parameter tool with no output schema and no annotations, the description covers the essential execution model, expected test shape, assertion vocabulary, result reporting, and writeExample behavior. It is not exhaustive on auth/config parameters, but it is complete enough to select and invoke the tool for its primary purpose.
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 60%, and the description adds meaningful semantics beyond the schema for the central file/tests parameters: it lists the YAML test fields and the assertion vocabulary used by expect. It also explains writeExample and the cs_chat relationship, though several config parameters rely on schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it runs a YAML test file against the published agent through cs_chat and reports pass/fail. It also distinguishes itself as the CLI-native complement to portal evaluations, so the agent can separate it from evaluation-run siblings such as cs_run_evaluation.
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: use a YAML test file with tests and expectations against the published agent, and use writeExample to scaffold a starter file. It does not explicitly state when not to use it or compare it directly with cs_run_evaluation, but the complement-to-portal-evaluations framing provides usable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an evaluation run for a test set (draft agent by default, or the published one). Optionally wait for completion and return the summary. mcsConnectionId runs it signed in as a user profile (the id of that user's Copilot Studio connection) so authenticated knowledge and tools answer; toolsConnections picks the connection each connector tool uses. Counts against the 20 runs per agent per 24h limit: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | ||
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| runName | No | ||
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| testSetId | Yes | ||
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| timeoutSeconds | No | ||
| mcsConnectionId | No | Copilot Studio connection id of the user profile to run as; omit for an anonymous run. Power Automate > Connections > Microsoft Copilot Studio, the GUID in the URL | |
| toolsConnections | No | Which connection each connector tool should use during the run | |
| runOnPublishedBot | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden and does disclose important behavior: draft-vs-published default, optional wait/summary, authenticated run via mcsConnectionId, connector connection selection, the 20-runs/24h quota, and the confirm:true requirement. It omits failure/timeout behavior and what is returned when wait is false.
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?
One front-loaded paragraph with no filler; the primary action and default target come first, followed by optional behavior and constraints. The auth sentence is dense but each clause carries operational 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 13-parameter tool with no annotations and no output schema, the description covers the main call contract, authentication, quota, and confirm gate. It leaves the non-wait return value and timeout semantics implicit, which an agent may need clarified.
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 62%, so the description needs to add value and does: it explains wait's effect, the published-bot switch, the confirm requirement, and the rationale for mcsConnectionId. Several parameters (runName, timeoutSeconds) remain undocumented beyond their names, keeping it from a 5.
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 ('Start an evaluation run for a test set') and clarifies the default target (draft agent) versus the published one. It does not explicitly name sibling alternatives like cs_get_evaluation_run or cs_run_conversation_tests, so it stops short of full 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?
Provides operating context (draft default, optional wait, confirm requirement, run quota) but never says when to choose this tool over cs_get_evaluation_run, cs_list_evaluation_runs, or cs_run_conversation_tests. Usage is implied by the name and defaults rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a run of a manually triggered cloud flow, with an optional payload. Only flows whose trigger is manual or agent-callable can be started this way; scheduled and event-driven flows run on their own. Whatever the flow does (sending mail, writing records) happens for real, so this changes a live environment: requires confirm: true. Uses the Power Automate service (cs_login scope 'flow'). Unverified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| flowId | Yes | Flow id (cs_list_flows) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| payload | No | Body for the trigger | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| triggerName | No | Trigger key inside the definition (cs_get_flow lists them); default 'manual' | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description carries the full burden well: it warns effects are real (mail sent, records written), that a live environment is mutated, that absent confirm the tool does a dry run, the required cs_login 'flow' scope, and that it is unverified against a live tenant. This is exactly the behavioral context an agent 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?
Front-loaded with the core action, then constraints, then safety warnings. Every sentence adds a distinct decision-relevant fact with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, side effects, auth scope, and reliability caveat, which is thorough for an 8-param mutation tool with no annotations. The one gap is that it never indicates what a successful call returns (e.g., a run id usable with cs_get_flow_run), leaving the follow-up path implicit.
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 baseline is 3; the description adds value by framing payload as optional and tying confirm to live-vs-dry-run behavior, and by restricting the eligible flowId population to manual triggers. It leaves auth/workspace/environment params entirely to the schema, which is acceptable at 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?
States a specific verb and resource ('Start a run of a manually triggered cloud flow') and explicitly scopes which flows qualify. It is distinguishable from siblings like cs_list_flow_runs and cs_get_flow_run without opening any schema.
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?
Gives both when-to-use and when-not: manual/agent-callable flows can be started, while 'scheduled and event-driven flows run on their own.' It also flags the confirm: true prerequisite, so the agent knows the call sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a pac auth profile the active one, by index (cs_init lists them) or name. Runs 'pac auth select' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| name | No | Profile name | |
| index | No | Profile index | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It names the command ('pac auth select') but does not disclose side effects: whether the change persists across sessions, whether it affects subsequent commands, required permissions, or reversibility. For a mutation tool this is a significant 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?
It is short and front-loads the purpose, but the trailing sentence ('Runs "pac auth select" with the active pac auth profile') is circular and slightly confusing, since selecting a profile to become active is what the tool does. It is more redundant than clarifying.
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 6-parameter mutation tool with no annotations and no output schema, the description is thin on behavioral context. The schema covers parameters well, but the description leaves out what happens to the previously active profile and the persistence/permission implications. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema. The description mentions selecting 'by index ... or name,' which simply restates what the schema already provides, adding no new syntax or format detail. 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 specific verb and resource ('Make a pac auth profile the active one'), which clearly distinguishes it from sibling tools like cs_create_auth_profile, cs_delete_auth_profile, and cs_list_auth_profiles. It even names the underlying CLI command, grounding the action unambiguously.
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 implies the usage (activating a profile) and points to cs_init as the place that lists profiles, which helps select the right index/name. However, it gives no explicit when-to-use vs. alternatives or conditions/exclusions, so guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch connector consent bypass on or off for one agent. On, end users stop being asked to approve the agent's connectors and the tools run straight away; off restores the consent prompt. An admin setting through the Power Platform API, so the signed-in user needs a Power Platform or Copilot Studio admin role. Changes a live environment: requires confirm: true. Follows the published Power Platform API reference; not yet verified against a live tenant.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| enabled | Yes | true switches the bypass on (no consent prompt), false switches it off | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description bears the full burden. It discloses critical operational behavior beyond the basic function, such as the specific impact of the bypass (end users stop being asked to approve) and the high-risk warning that the tool 'not yet verified against a live tenant.'
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 highly dense and effective. It front-loads the core function and then efficiently stacks the necessary contextual details (effect, permission, warning) using minimal, impactful language.
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 administrative action tool, this description is exceptionally complete. It covers the functional effect, the necessary permissions, the operational requirements (admin API setting), and a critical technical caveat (unverified in live tenant), leaving no major call-to-action gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, providing a solid baseline. The description adds useful semantic context, specifically explaining the real-world consequence of the 'enabled' boolean (no consent prompt vs. restores prompt) and defining the practical use of the 'confirm' parameter for live environments.
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 action verb ('Switch') applied to a distinct resource ('connector consent bypass') and clearly defines the scope ('for one agent'). This differentiates it from related getter tools like cs_get_connector_consent_bypass.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions on prerequisites, stating the user must have a 'Power Platform or Copilot Studio admin role.' Furthermore, it outlines the conditional usage of the tool by stating that live changes 'requires confirm: true'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch a flow on (Activated) or off (Draft). This is the step a solution import leaves for you: flows whose connection references were unbound at import time land switched off. A flow can only be turned on once its connections are bound and its definition is valid. Changes a live environment: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | on = Activated, off = Draft | |
| flowId | Yes | Flow (workflow) id | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses this mutates a live environment, that confirm: true is required to actually apply, and that a flow can only be activated once connections are bound and the definition is valid. It omits permission/auth requirements and failure behavior, keeping it out of the top band.
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 tight sentences, front-loaded with the action and its two states, then the post-import rationale, then the precondition and the confirm requirement. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter mutation tool with no annotations and no output schema, the description covers what changes, when it is needed, the gating precondition, and the confirm requirement. It leaves auth/identity parameter behavior (clientId, tenantId, workspace) entirely to the schema, which is acceptable given 100% schema coverage.
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 every parameter including the on/off enum mapping and confirm semantics. The description restates the state values and confirm requirement but adds no format or interaction detail 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?
States a specific verb and resource ('Switch a flow on ... or off') and pins the exact state values (Activated/Draft). This clearly separates it from siblings like cs_update_flow (definition edits) and cs_bind_flow_connection (connection binding).
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?
Gives strong when-to-use context: it is the follow-up step after a solution import that left flows off, and it states the precondition (connections bound, definition valid) for turning a flow on. It does not name the sibling to use for binding connections (cs_bind_flow_connection), so it stops just short of explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the version in a local unpacked solution's Solution.xml, explicitly or by strategy (gittags, filetracking, solution). Local file change only. Runs 'pac solution version' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| filename | No | Tracker CSV for the filetracking strategy | |
| strategy | No | Version strategy (see pac solution version help) | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| buildVersion | No | Build version | |
| solutionPath | No | Unpacked solution folder or Solution.xml | |
| timeoutSeconds | No | Default 600 | |
| revisionVersion | No | Revision version |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that this is a local file change only and that it runs 'pac solution version' with the active pac auth profile, but it leaves out failure behavior, reversibility, validation, and whether existing version data is overwritten.
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 compact sentences with the core operation and local-only constraint front-loaded. Every sentence contributes useful information without 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?
The definition gives enough context to understand the core operation, especially the local-file-only scope, and the schema is fully described. However, with no annotations and no output schema, the description should say more about side effects, expected result, or error conditions for a mutation tool with nine 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 nine parameters. The description adds some meaning by mentioning explicit versions versus strategy-based versions and naming gittags, filetracking, and solution, but it does not explain most parameter interactions or formats 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 states a specific verb and resource: it updates the version in a local unpacked solution's Solution.xml. The phrase 'Local file change only' clearly distinguishes it from online-version or deployment-oriented siblings such as cs_solution_online_version, and the strategy names add concrete scope.
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 when to use the tool by specifying local Solution.xml updates and naming strategies, but it does not explicitly state when to choose this over alternatives like cs_solution_online_version or cs_upgrade_solution. Usage is inferable rather than fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer 'there are too many tools': narrow, or restore, the tool list for the rest of this session. The full list is 146 tools and about 50k tokens of schema, which crowds a smaller model's context and makes it choose worse. Presets: core (the loop that builds an agent and gets it live), authoring (local files only), admin (tenant administration), solutions (moving solutions between environments), full (everything). Read-only: it changes nothing in any environment and no tool is lost, only hidden. Ask the user before calling it.
| Name | Required | Description | Default |
|---|---|---|---|
| keep | No | Extra tool names to keep on top of the preset | |
| preset | Yes | Which set to offer for the rest of this session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it discloses session scope, that it is read-only, that nothing in any environment changes, that no tool is lost (only hidden), and that user confirmation is required first.
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 problem it solves and the action, then the preset vocabulary, then the safety facts. Dense but nearly every clause carries information; the token-count rationale is slightly verbose but justifies the tool's existence.
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?
No output schema and no annotations, yet the description covers purpose, all preset options, reversibility, scope, and required confirmation. An agent has everything needed to invoke this correctly without further context.
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, but the description goes beyond the raw enum by explaining what each preset actually contains (core, authoring, admin, solutions, full) — genuine semantic value for choosing a value. The 'keep' parameter is left to 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 concrete verb+resource: narrow or restore the offered tool list for the session. It also quantifies the problem (146 tools, ~50k tokens of schema) so the agent knows exactly what the tool governs, and no sibling does anything comparable.
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?
Gives a clear trigger ("Answer 'there are too many tools'") and an explicit procedural rule ("Ask the user before calling it"). It does not state when not to use it, but there is no sibling that overlaps, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture one environment into a folder for comparison or history: solution version, every agent cloned with pac copilot clone (agents/), and, when signed in, flows, connection references, environment variables and publish state. Read-only for the environment.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Snapshot folder (recreated) | |
| label | Yes | Short name such as DEV, TEST, ACC, PROD | |
| agents | No | Agent schema names or ids to clone; default: every agent pac copilot list returns | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| solution | No | Solution unique name to record version/managed state for | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| maxAgents | No | Default 20 | |
| environment | Yes | Environment id or URL | |
| includeDataverse | No | Default true: flows, connection references, environment variables and publish state via Dataverse (needs cs_login; skipped silently otherwise) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the environment is read-only, that agents are cloned with pac copilot clone into agents/<name>, and that Dataverse-sourced items are included only when signed in and are skipped silently otherwise. These are meaningful behavioral details, though it could further explain failure modes or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it begins with the core action, then lists captured artifacts, then closes with the read-only guarantee. Every sentence contributes useful information, and there is 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 nine parameters, no output schema, and no annotations, the description provides enough context to understand what the tool captures and its read-only nature. It even indicates the folder layout for agents (agents/<name>). It stops short of describing the returned snapshot structure or how comparison/history should consume the folder, but the essentials are 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 description coverage is 100%, so the input schema already documents all nine parameters, including agent selection, solution name, and includeDataverse behavior. The description adds some context about what gets captured and the signed-in condition for Dataverse items, but it does not significantly extend parameter meaning beyond the schema. A 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 specific verb and resource: capture one environment into a folder for comparison or history. It also enumerates what gets captured: solution version, agents, flows, connection references, environment variables, and publish state. It does not explicitly distinguish itself from sibling comparison tools such as cs_compare_snapshots or cs_compare_environments, 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 'for comparison or history' implies the intended use case, and 'Read-only for the environment' clarifies the operation's nature. However, the description does not explicitly say when to use this tool versus alternatives like cs_compare_snapshots, cs_compare_environments, or cs_check_drift. Usage guidance is therefore only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Without solutionVersion: read the version of a solution in the environment. With it: set that version (mutating). Runs 'pac solution online-version' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise). Only some inputs mutate; see the parameter descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| solutionName | Yes | Solution unique name | |
| timeoutSeconds | No | Default 600 | |
| solutionVersion | No | New version to set; omit to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses that the tool mutates a live environment, that confirm: true is required to actually mutate (dry run otherwise), that only some inputs mutate, and that it runs under the active pac auth profile. It does not discuss reversibility or what happens to concurrent versions, but the core safety profile is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the read/set distinction and the mutation caveat before the pac command detail. Slightly redundant tail ('Only some inputs mutate; see the parameter descriptions') points the reader back to the schema, but overall it is tight and well ordered.
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 dual-mode tool with no annotations and no output schema, the description covers the critical decision points: which mode is triggered by which input and the confirm-gated mutation behavior. It does not describe return values or pagination, but that is secondary compared to the mutation safety it does disclose.
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 eight parameters in detail (confirm, background, profile, environment, etc.). The description mainly reinforces the solutionVersion semantics and the confirm/dry-run rule; it is accurate but largely additive rather than meaningfully expanding on 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?
States a specific verb+resource ('read the version of a solution' vs 'set that version') and explains the switch condition (presence of solutionVersion). It clearly separates the two modes, but does not differentiate itself from close siblings such as cs_set_solution_version or cs_upgrade_solution, which an agent could easily confuse it with.
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?
Gives explicit context for both modes: omit solutionVersion to read, provide it to set; and it states that mutation requires confirm: true or a dry run results. However, it names no alternative tool despite cs_set_solution_version existing as a near-identical sibling, so an agent gets no routing guidance between the two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pac copilot status for an agent id.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only status query, but it does not state permissions, side effects, return content, or whether the operation is safe/non-destructive.
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?
It is a single short sentence with no wasted words, but it is under-specified rather than optimally structured. The fragment is concise, though it provides little front-loaded context beyond the command name.
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?
There is no output schema and no annotations, and the description does not explain what status data is returned or how to interpret it. The schema covers parameters, but important behavioral and output context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three optional parameters, including defaults, so parameter semantics are already well documented. The description only mentions the agent id and adds no meaning beyond the schema, making the baseline score 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?
It names a specific underlying command (pac copilot status) and the agent-id input, but "status" is vague and does not say what status is being checked or distinguish this from siblings like cs_job_status, cs_check_drift, or cs_review_agent. The title adds "provisioning" context, but the description alone is thin.
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 use this tool, when not to use it, or which sibling alternatives apply. The agent must infer its role from the name and surrounding tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate over recent sessions: how they ended, the escalation rate, average turns, how many never matched a topic, the topics and tools that actually fire, and the questions behind the sessions that went badly. Read-only. This is the input for deciding what to fix next, and for cs_create_test_set_csv fromTranscripts.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum sessions to read (default 100, max 500) | |
| days | No | Window in days (default: everything returned) | |
| topN | No | How many topics/tools/questions to list (default 10) | |
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It does state 'Read-only' and lists the aggregate content returned, but it does not disclose auth requirements, rate limits, execution cost, or whether output format is structured versus narrative, leaving meaningful behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then moves to usage. Its first sentence is long because it enumerates many returned metrics, but every listed item is useful for understanding output scope, and the separate 'Read-only' and downstream-use sentences are efficient.
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 eight-parameter, read-only aggregation tool with no output schema, the description covers the essential return categories and the primary decision-making use case. It leaves some operational details to the schema, but no output schema exists and the description is still sufficient for an agent to understand what the tool produces.
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 eight optional parameters, including their defaults. The description adds no parameter-level semantics beyond what the schema provides, making the baseline 3 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 specific verb (Aggregate) and resource (recent sessions) and enumerates the exact metrics produced: session endings, escalation rate, average turns, unmatched-topic counts, firing topics/tools, and questions from bad sessions. It also identifies a downstream sibling (cs_create_test_set_csv fromTranscripts), which helps distinguish its role, though it does not explicitly contrast with other transcript-related siblings like cs_list_transcripts or cs_get_transcript.
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 use: 'This is the input for deciding what to fix next, and for cs_create_test_set_csv fromTranscripts.' That tells an agent when the tool is relevant and what downstream workflow it feeds, but it stops short of explicit when-not guidance or naming alternatives for raw transcript access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-export the solution and update an existing unpacked solution folder or .cdsproj with the environment's current state. Read-only for the environment. Runs 'pac solution sync' with the active pac auth profile.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| map | No | Mapping XML file for component folders | |
| async | No | Run the operation asynchronously | |
| include | No | Settings to include in the export (pac solution export --include values) | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| localize | No | Extract string resources into .resx files | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| packageType | No | Unmanaged, Managed or Both (default Both) | |
| solutionFolder | No | Unpacked solution folder (Other/Solution.xml root) or .cdsproj folder; default: cwd | |
| timeoutSeconds | No | Default 3600 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full burden, and it does add real context: the operation is 'read-only for the environment' and runs 'pac solution sync' with the active auth profile. The critical gap is the local side — it does not say whether local unpacked files are overwritten or whether local edits are lost, nor what the sync returns.
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, zero filler, and the core action (re-export and update the local project) is front-loaded before the safety note and implementation detail. 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 12-parameter, zero-required, annotation-free mutation-of-local-files tool with no output schema, the description is adequate but thin. It covers direction and the environment-side safety property but omits the local overwrite semantics and result shape that an agent would need to call it responsibly.
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 12 parameters are already documented in the schema, including profile defaults, solutionFolder, environment and packageType. The description adds essentially nothing beyond the parameter layer except that it uses the active pac auth profile. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: re-export the solution and update an existing unpacked folder or .cdsproj, plus the underlying command ('pac solution sync'). The word 'existing' implicitly separates it from creation-style siblings like cs_init_solution_project or cs_clone_solution, though it never names cs_pull_solution/cs_import_solution as the contrasting alternatives.
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?
Usage is implied by scope ('update an EXISTING unpacked solution folder or .cdsproj'), which tells the agent it needs a solution project already on disk. However there is no explicit when-to-use/when-not statement and no sibling is named, so routing between this, cs_pull_solution, cs_check_solution and cs_pack_solution is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write the portal's import CSV from questions people actually asked, most frequent first, instead of guessing from the workspace. onlyFailed (default true) keeps the sessions that escalated, went unanswered or were abandoned, which are the ones worth turning into regression cases. Read-only apart from writing the file; import it once in the portal, then cs_run_evaluation automates the runs.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum sessions to read (default 100, max 500) | |
| days | No | Only sessions from the last N days | |
| botId | No | Agent (bot) id. Defaults to workspace sync metadata or CPS_AGENT_ID. | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| maxCases | No | Maximum cases in the CSV (portal limit is 100) | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| onlyFailed | No | Default true: only sessions that escalated, went unresolved or were abandoned | |
| outputPath | No | Default <workspace>/../<agent>-transcript-testset.csv | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and does disclose the key side effect: 'Read-only apart from writing the file.' It also reveals the data source (real sessions), the ordering (most frequent first), and the semantics of onlyFailed as a filter for escalation/unanswered/abandoned sessions. It does not address auth prerequisites or volume/latency, but it is materially more informative than a bare mutation statement.
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 tight sentences, front-loaded with the verb and artifact, then the filtering rule, then the workflow handoff. No filler and nothing repeated from the 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 10-parameter, all-defaulted CSV-generation tool with no output schema, the description covers the data source, filter behavior, ordering, write side effect, and the follow-up tool. It could say more about auth/setup prerequisites, but the required workflow 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 description coverage is 100%, so the schema already documents all ten parameters and the baseline is 3. The description adds only the 'most frequent first' ordering (relevant to top/maxCases) and a rationale for onlyFailed, but gives no extra syntax or format detail 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 concrete verb and output artifact: 'Write the portal's import CSV from questions people actually asked, most frequent first.' It also implicitly distinguishes itself from the workspace-guessing path ('instead of guessing from the workspace'), which maps to the cs_create_test_set_csv sibling, though it never names that sibling directly.
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?
Gives clear context (build a test set from real transcripts, filter with onlyFailed) and names the downstream step explicitly: 'import it once in the portal, then cs_run_evaluation automates the runs.' It stops short of stating when NOT to use this (e.g. when cs_create_test_set_csv is preferred), so it is context-rich but not exclusive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit agent.mcs.yml (standard harness): instructions, display name, conversation starters, model hint, and the settings the portal groups under responses and generative AI: response instructions (wording and formatting), response mode, conversation history, capability toggles (web browsing, code interpreter, image generation, Teams / SharePoint / email / meeting / people search), whether the model may use its own general knowledge, content moderation level, file analysis and semantic search. The first call writes nothing: it returns the change - the current lines against the proposed ones, and the instruction character count against the 8000 the product allows - and the file is written on a second call with confirm: true. Local file change; cs_push applies it. For GitHub Copilot harness (cli-copilot) workspaces the instructions go into settings.mcs.yml.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| history | No | Whether the agent sees conversation history | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| displayName | No | ||
| capabilities | No | Capability toggles; only the ones you pass are changed | |
| instructions | No | Replace the instructions | |
| modelNameHint | No | Model hint, e.g. GPT5Chat | |
| historyMessages | No | How many past user messages to include (with history: conversation) | |
| contentModeration | No | ||
| useModelKnowledge | No | Whether the model may answer from its own general knowledge as well as the knowledge sources | |
| appendInstructions | No | Add a paragraph to the instructions | |
| defaultResponseMode | No | Response mode: Auto, ThinkDeeper (more reasoning, slower) or QuickResponse | |
| conversationStarters | No | ||
| responseInstructions | No | How answers should be worded and formatted (Settings > Responses > Response formatting in the portal), separate from the main instructions. Capped at 500 characters. | |
| isFileAnalysisEnabled | No | ||
| addConversationStarters | No | ||
| isSemanticSearchEnabled | No | ||
| appendResponseInstructions | No | Add a line to the response formatting, within the same 500 characters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the dry-run/preview semantics, the 8000-character instruction cap and 500-character response-instruction cap, that changes are local to the file, and the harness-dependent target file. It omits some behavioral detail (e.g. what happens on partial/unknown fields), but is substantially informative.
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?
Dense but front-loaded, leading with the file and field list before the preview/confirm mechanics. Slightly run-on and long for one paragraph, but every clause is load-bearing given 18 params.
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 18-parameter, no-output-schema, no-annotation mutation tool, the description covers the critical mechanics: preview vs write, limits, target file, and push requirement. It leaves a few lower-priority params (semantic search, file analysis, moderation levels) to the schema, which is acceptable.
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?
Adds real meaning beyond the 67%-covered schema: it maps fields to portal locations (responses, generative AI), explains the difference between instructions/appendInstructions and responseInstructions/appendResponseInstructions, and calls out the 500-char cap. Some params (contentModeration levels, historyMessages interaction, isSemanticSearchEnabled) lack added 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?
States a specific verb and resource (edit agent.mcs.yml) and enumerates exactly which settings it touches. It also names the harness variant (cli-copilot → settings.mcs.yml) and the downstream sibling (cs_push), so an agent can distinguish it from generic settings 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?
Explains the two-call flow clearly: first call is a preview, writing requires confirm: true. It also says cs_push applies the change. It does not explicitly contrast with cs_update_settings or say when not to use it, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rotate the app registration or secret behind a service-principal Dataverse connection. Runs 'pac connection update' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| tenantId | Yes | Entra tenant id | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| clientSecret | Yes | New client secret (masked in logs) (masked in logs and results) | |
| connectionId | Yes | Connection id (cs_list_connections) | |
| applicationId | Yes | App registration (client) id | |
| timeoutSeconds | No | Default 600 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the underlying command, that it mutates a live environment, and that the confirm flag gates the mutation into a dry run otherwise. It does not state reversibility of the rotated secret, permission requirements, or whether the old secret is revoked, which keeps it from a 5.
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 tight sentences with the destructive nature and the confirm gate front-loaded after the purpose statement. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description supplies the critical safety information (live mutation, confirm gate, dry-run fallback) and the execution mechanism. Missing details on permissions, secret revocation, and failure behavior are minor gaps but would round out the picture.
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 ten parameters including confirm, clientSecret masking, and profile resolution. The description only reinforces the confirm parameter, adding no syntax or format detail beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: rotating the app registration or secret behind a service-principal Dataverse connection. This clearly distinguishes it from siblings like cs_create_connection, cs_delete_connection, and cs_list_connections, and even from cs_admin_register_application.
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?
Gives clear operating context: it runs 'pac connection update' under the active pac auth profile and requires confirm: true for a live change, otherwise it is a dry run. It stops short of naming alternatives (e.g. use cs_create_connection for a new connection), so the when-not-to-use case is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a flow's name, description or definition in the environment. Pass 'steps' (and optionally 'trigger') to rebuild the definition the way cs_build_flow_definition does, or 'definition' for a ready-made one; either replaces properties.definition inside the existing clientdata and keeps the connection references. 'clientData' replaces the whole document. Read the current one with cs_get_flow includeDefinition first. Managed flows cannot be edited in place; edit them in their source environment or through a solution. Changes a live environment: requires confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| steps | No | Steps in order; each waits for the previous one to succeed | |
| flowId | Yes | Flow (workflow) id | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| outputs | No | What the flow answers with (agent-callable and HTTP flows) | |
| trigger | No | Default: 'agent' (When an agent calls the flow) | |
| clientId | No | Entra app (client) id for MSAL. Defaults to CPS_CLIENT_ID, then the first-party VS Code id. | |
| tenantId | No | Entra tenant id. Defaults to the workspace sync metadata, then CPS_TENANT_ID. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. | |
| clientData | No | The whole clientdata document; overrides 'definition' | |
| definition | No | Power Automate definition object (properties.definition), instead of steps | |
| description | No | ||
| dataverseUrl | No | Dataverse URL; default: from the workspace or the environment | |
| environmentId | No | Power Platform environment id (GUID). Defaults to workspace sync metadata or CPS_ENVIRONMENT_ID. | |
| connectionReferences | No | Connection reference entries to add or explicitly replace; existing entries are otherwise preserved | |
| connectionReferencePrefix | No | Prefix for generated connection reference names, usually your publisher prefix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations the description carries the full burden and does so: it discloses the destructive scope ('clientData' replaces the whole document; steps/definition replace properties.definition inside the existing clientdata while preserving connection references), the live-environment confirm requirement, and the managed-flow immutability restriction that appears in no structured field.
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?
One front-loaded paragraph that opens with the verb and keeps the highest-risk facts (whole-document replacement, managed-flow restriction, confirm) present; each sentence adds information. It is dense and semicolon-chained rather than scannable, which keeps it short of a 5.
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 16-parameter mutation tool with no annotations and no output schema, the description covers the mutation paths, safety gate, and prerequisites an agent needs to invoke it correctly. It does not describe the response shape, though the dry-run/pass-through behavior implied by confirm is at least referenced.
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 88%, so the baseline is 3, but the description adds real value by explaining the mutual-exclusion/override relationship among steps/trigger, definition, and clientData — semantics the per-field schema text only partially conveys ('overrides definition').
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 ('Change a flow's name, description or definition') and immediately disambiguates the three mutation paths (steps/trigger, definition, clientData). Named siblings cs_build_flow_definition and cs_get_flow let an agent separate this from building or reading flows without opening schemas.
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 routes the agent: use 'steps' like cs_build_flow_definition, or a ready-made 'definition', or 'clientData'. It names when-not ('Managed flows cannot be edited in place; edit them in their source environment or through a solution') and prescribes the prerequisite ('Read the current one with cs_get_flow includeDefinition first').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set values in settings.mcs.yml by dot path, e.g. {"configuration.settings.GenerativeActionsEnabled": true}. Do not change authoringModel/recognizer/template. The first call changes nothing: it returns the files it would write, as a diff against what is there now, for the user to approve. Call it again with the same arguments plus confirm: true to write them.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| confirm | No | Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing. | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers the single most important non-obvious behavior: the first call is a no-op that returns a diff of files it would write, and the write only occurs on a second call with confirm: true. That is strong and unusual disclosure. It stops short of stating permission/auth requirements or whether writes are reversible.
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 purpose, then the field restriction, then the critical two-phase commit behavior placed last because it is the last thing an agent must act on. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description usefully explains what the first call returns (files to write, as a diff). For a mutation tool with zero annotations, the confirm gate covers the key safety concern. Remaining gaps are minor (auth/permission prerequisites, error behavior).
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 67%, and the least-documented parameter is patch (bare object with no description). The description compensates by explaining the dot-path key syntax and demonstrating a nested example value, and it explicitly ties confirm: true to the write step. Workspace is left to its schema 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?
States a specific verb and resource ('Set values in settings.mcs.yml') plus the addressing mechanism (dot path) with a concrete example. An agent can tell it apart from sibling mutators like cs_update_agent or cs_update_flow, which target different files/objects.
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?
Gives explicit operating rules: the dot-path key format, the excluded fields (authoringModel/recognizer/template), and the two-step preview-then-confirm protocol with the exact argument to add. It does not, however, contrast itself against any sibling tool, so 'vs alternatives' is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete a managed solution upgrade that was imported as a staged upgrade (pac solution import --stage-and-upgrade or the portal's 'Stage for upgrade'). Runs 'pac solution upgrade' with the active pac auth profile. Mutates a live environment: requires confirm: true (a dry run otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for pac (for project commands: the solution project folder) | |
| async | No | Run the operation asynchronously | |
| confirm | No | Required to actually perform a change in a live environment. Without it the tool returns a dry run. | |
| profile | No | pac auth profile to run as: the admin account for tenant commands. Defaults to CPS_ADMIN_PROFILE for admin commands and CPS_PAC_PROFILE otherwise, then the active profile. cs_init lists the profiles. | |
| background | No | Run in the background and return a jobId immediately, for a command that takes longer than the client will wait. Poll cs_job_status. | |
| environment | No | Environment id or URL; default: the environment of the active pac auth profile | |
| solutionName | Yes | Solution unique name | |
| timeoutSeconds | No | Default 3600 | |
| maxAsyncWaitTime | No | Max asynchronous wait time in minutes (default 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does so well: it discloses that this mutates a live environment, that confirm: true is required to commit, and that omitting it yields a dry run. It does not state reversibility/irreversibility or failure behavior, which matters for a mutation tool on a live tenant.
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 tight sentences: what it is, how it runs, and the safety constraint, with the mutation/confirm warning front-loaded at the end where it is most salient. No filler or repetition of the 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 an unannotated mutation tool with 100% schema coverage and no output schema, the description supplies the critical behavioral facts (live-environment mutation, confirm gate, dry-run fallback, auth profile). Only failure/rollback behavior and a hint about the dry-run/result shape are 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 schema already documents all nine parameters including confirm and profile. The description reinforces the confirm semantics and mentions the active pac auth profile, but adds no syntax or format details beyond the schema. Baseline 3 is correct.
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?
Specific verb+resource ('Complete a managed solution upgrade') with the precondition that the solution was imported as a staged upgrade, which cleanly distinguishes it from cs_import_solution and cs_deploy_solution. It even names the upstream mechanism (pac solution import --stage-and-upgrade / 'Stage for upgrade'), so the agent knows exactly which lifecycle step this covers.
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 precondition is stated explicitly: use this only for a solution already imported as a staged upgrade. That is a clear when-to-use condition, but it never names the sibling to use for the import/deploy steps themselves, so a novice agent is left to infer cs_import_solution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural validation of every component file against the Copilot Studio authoring schema (kinds, unknown/missing properties, duplicate ids, placeholders, Power Fx prefixes, variable scopes) plus cross-file checks (connection references, topic redirects). Answers 'is anything broken in these files?'; it only reads them and sends nothing anywhere. cs_push runs it itself and blocks on errors.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Validate a single file (relative to workspace) | |
| workspace | No | Path to (or inside) the agent workspace. Defaults to CPS_WORKSPACE or the current directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses that the tool only reads files and sends nothing anywhere (safety profile), and that cs_push invokes it and blocks on errors. It stops short of describing the failure/report shape (e.g., whether it throws or returns a findings list), which would matter for an agent acting on results.
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, then a parenthetical enumeration of checks, then the usage/relationship sentence. Every sentence carries information; the parenthetical is dense but each item is substantive rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only validation tool with no output schema and no annotations, the description covers what is validated, that it is side-effect free, and how it relates to cs_push. The main gap is the shape of the result an agent must interpret, but otherwise the definition is sufficient to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (file, workspace) are already documented in the schema. The description adds scope information ('every component file', 'cross-file checks') but says nothing about the file-vs-workspace selection semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Structural validation of every component file') and enumerates exactly what is checked: schema kinds, unknown/missing properties, duplicate ids, placeholders, Power Fx prefixes, variable scopes, plus cross-file checks. This is far more specific than the sibling cs_check_solution or cs_check_drift, and an agent can tell them apart without opening schemas.
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?
Frames the use case crisply ('is anything broken in these files?') and names the related tool cs_push, noting it runs validation itself and blocks on errors. It does not, however, explicitly distinguish itself from sibling checks like cs_check_solution or cs_check_drift, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.8cs_add_flow4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / actions / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / inputs / items / additionalPropertiesRemoved value: -falseInput schema / properties / outputs / items / additionalPropertiesRemoved value: -falsecs_add_knowledge_source1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_add_solution_component1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_add_solution_license1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_add_solution_reference1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_add_tool3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / action / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / inputs / items / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "type": "string"
- },
- "entity": {
- "type": "string"
- },
- "kind": {
- "const": "automatic",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "shouldPromptUser": {
- "type": "boolean"
- }
- },
- "required": [
- "kind",
- "name",
- "description"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "kind": {
- "const": "manual",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "value": {
- "description": "Literal or Power Fx (=System.User.Email)",
- "type": "string"
- }
- },
- "required": [
- "kind",
- "name",
- "value"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "entity": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "automatic",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "shouldPromptUser": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "description"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "value": {
+ "description": "Literal or Power Fx (=System.User.Email)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ }
+]cs_add_topic4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / definitionsAdded value: +{
+ "__schema0": {
+ "oneOf": [
+ {
+ "properties": {
+ "speak": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+ },
+ "text": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+ },
+ "type": {
+ "const": "message",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "allowInterruption": {
+ "type": "boolean"
+ },
+ "choices": {
+ "description": "Multiple-choice options (closed list) instead of an entity",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "entity": {
+ "enum": [
+ "String",
+ "Boolean",
+ "Number",
+ "Email",
+ "Date",
+ "DateTime",
+ "PhoneNumber",
+ "URL",
+ "Money",
+ "PersonName",
+ "City",
+ "CountryOrRegion",
+ "Organization",
+ "Percentage",
+ "Age",
+ "Duration",
+ "Color",
+ "Language",
+ "ZipCode",
+ "StreetAddress",
+ "File"
+ ],
+ "type": "string"
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "type": {
+ "const": "question",
+ "type": "string"
+ },
+ "variable": {
+ "description": "Topic.Name (prefix optional)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "prompt",
+ "variable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "cases": {
+ "items": {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "condition": {
+ "description": "Power Fx, e.g. Topic.Choice = \"Yes\"",
+ "type": "string"
+ }
+ },
+ "required": [
+ "condition",
+ "actions"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "else": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "condition",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "cases"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "replace": {
+ "type": "boolean"
+ },
+ "topic": {
+ "description": "Topic name or full reference",
+ "type": "string"
+ },
+ "type": {
+ "const": "redirect",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "topic"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "type": {
+ "const": "setVariable",
+ "type": "string"
+ },
+ "value": {
+ "type": [
+ "string",
+ "number",
+ "boolean"
+ ]
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "variable",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "autoSend": {
+ "type": "boolean"
+ },
+ "endIfAnswered": {
+ "type": "boolean"
+ },
+ "sources": {
+ "description": "Restrict to these knowledge sources (file stems from knowledge/, or full references)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "searchKnowledge",
+ "type": "string"
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "card": {
+ "anyOf": [
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+ ],
+ "description": "Adaptive Card JSON (object or string), version 1.5"
+ },
+ "outputTypes": {
+ "additionalProperties": {
+ "enum": [
+ "String",
+ "Number",
+ "Boolean"
+ ],
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "outputs": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Input card: card field id -> Topic variable; omit for a display-only card",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "card",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "card"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "message": {
+ "description": "Message to the human agent",
+ "type": "string"
+ },
+ "phoneNumber": {
+ "description": "Transfer to a phone number instead of an agent",
+ "type": "string"
+ },
+ "type": {
+ "const": "transfer",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "type": {
+ "const": "endConversation",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "body": {},
+ "headers": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "method": {
+ "enum": [
+ "Get",
+ "Post",
+ "Put",
+ "Patch",
+ "Delete"
+ ],
+ "type": "string"
+ },
+ "responseVariable": {
+ "type": "string"
+ },
+ "type": {
+ "const": "http",
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "responseVariable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "flowId": {
+ "type": "string"
+ },
+ "input": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "invokeFlow",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "flowId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "clearTopicQueue": {
+ "type": "boolean"
+ },
+ "type": {
+ "const": "end",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "node": {
+ "additionalProperties": {},
+ "description": "A full DialogAction node; 'id' is added if missing",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "raw",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "node"
+ ],
+ "type": "object"
+ }
+ ]
+ }
+}Input schema / properties / actions / items / $refAdded value: +"#/definitions/__schema0"Input schema / properties / actions / items / anyOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "speak": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- },
- "text": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- },
- "type": {
- "const": "message",
- "type": "string"
- }
- },
- "required": [
- "type",
- "text"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "allowInterruption": {
- "type": "boolean"
- },
- "choices": {
- "description": "Multiple-choice options (closed list) instead of an entity",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "entity": {
- "enum": [
- "String",
- "Boolean",
- "Number",
- "Email",
- "Date",
- "DateTime",
- "PhoneNumber",
- "URL",
- "Money",
- "PersonName",
- "City",
- "CountryOrRegion",
- "Organization",
- "Percentage",
- "Age",
- "Duration",
- "Color",
- "Language",
- "ZipCode",
- "StreetAddress",
- "File"
- ],
- "type": "string"
- },
- "prompt": {
- "type": "string"
- },
- "type": {
- "const": "question",
- "type": "string"
- },
- "variable": {
- "description": "Topic.Name (prefix optional)",
- "type": "string"
- }
- },
- "required": [
- "type",
- "prompt",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "cases": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/actions/items"
- },
- "type": "array"
- },
- "condition": {
- "description": "Power Fx, e.g. Topic.Choice = \"Yes\"",
- "type": "string"
- }
- },
- "required": [
- "condition",
- "actions"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "else": {
- "items": {
- "$ref": "#/properties/actions/items"
- },
- "type": "array"
- },
- "type": {
- "const": "condition",
- "type": "string"
- }
- },
- "required": [
- "type",
- "cases"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "replace": {
- "type": "boolean"
- },
- "topic": {
- "description": "Topic name or full reference",
- "type": "string"
- },
- "type": {
- "const": "redirect",
- "type": "string"
- }
- },
- "required": [
- "type",
- "topic"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "type": {
- "const": "setVariable",
- "type": "string"
- },
- "value": {
- "type": [
- "string",
- "number",
- "boolean"
- ]
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "variable",
- "value"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "autoSend": {
- "type": "boolean"
- },
- "endIfAnswered": {
- "type": "boolean"
- },
- "sources": {
- "description": "Restrict to these knowledge sources (file stems from knowledge/, or full references)",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "type": {
- "const": "searchKnowledge",
- "type": "string"
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "card": {
- "anyOf": [
- {
- "additionalProperties": {},
- "type": "object"
- },
- {
- "type": "string"
- }
- ],
- "description": "Adaptive Card JSON (object or string), version 1.5"
- },
- "outputTypes": {
- "additionalProperties": {
- "enum": [
- "String",
- "Number",
- "Boolean"
- ],
- "type": "string"
- },
- "type": "object"
- },
- "outputs": {
- "additionalProperties": {
- "type": "string"
- },
- "description": "Input card: card field id -> Topic variable; omit for a display-only card",
- "type": "object"
- },
- "type": {
- "const": "card",
- "type": "string"
- }
- },
- "required": [
- "type",
- "card"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "message": {
- "description": "Message to the human agent",
- "type": "string"
- },
- "phoneNumber": {
- "description": "Transfer to a phone number instead of an agent",
- "type": "string"
- },
- "type": {
- "const": "transfer",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "type": {
- "const": "endConversation",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {},
- "headers": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "method": {
- "enum": [
- "Get",
- "Post",
- "Put",
- "Patch",
- "Delete"
- ],
- "type": "string"
- },
- "responseVariable": {
- "type": "string"
- },
- "type": {
- "const": "http",
- "type": "string"
- },
- "url": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "url",
- "responseVariable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "flowId": {
- "type": "string"
- },
- "input": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "output": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "type": {
- "const": "invokeFlow",
- "type": "string"
- }
- },
- "required": [
- "type",
- "flowId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "clearTopicQueue": {
- "type": "boolean"
- },
- "type": {
- "const": "end",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "node": {
- "additionalProperties": {},
- "description": "A full DialogAction node; 'id' is added if missing",
- "type": "object"
- },
- "type": {
- "const": "raw",
- "type": "string"
- }
- },
- "required": [
- "type",
- "node"
- ],
- "type": "object"
- }
-]cs_add_trigger1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_add_variable1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_add_environment_to_group1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_assign_group1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_assign_user1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_assign_users2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / assignments / items / additionalPropertiesRemoved value: -falsecs_admin_backup_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_copy_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_create_environment7 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / appVersionAdded value: +{
+ "description": "(Preview) Pin the application build, e.g. 10.0.43; Finance & Operations and Project Operations templates only",
+ "type": "string"
+}Input schema / properties / enableDemoDataAdded value: +{
+ "description": "(Preview) Install demo data; Finance & Operations and Project Operations templates only",
+ "type": "boolean"
+}Input schema / properties / enableDevToolsAdded value: +{
+ "description": "(Preview) X++ developer tooling; Finance & Operations and Project Operations templates only, ignored otherwise",
+ "type": "boolean"
+}Input schema / properties / enableTestModulesAdded value: +{
+ "description": "(Preview) Install the F&O test modules; Finance & Operations and Project Operations templates only",
+ "type": "boolean"
+}Input schema / properties / macroRegionAdded value: +{
+ "description": "Macro-region id instead of a region, for tenants with Advanced Data Residency (pac 2.12)",
+ "enum": [
+ "asia-pacific",
+ "emea",
+ "eu-efta",
+ "europe-uk",
+ "north-america",
+ "the-americas"
+ ],
+ "type": "string"
+}Input schema / properties / platformVersionAdded value: +{
+ "description": "(Preview) Pin the platform build, e.g. 7.0.7256; needs appVersion",
+ "type": "string"
+}cs_admin_create_service_principal1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_delete_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_environment_status1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_app_templates1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_applications1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_backups1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_dlp_policies1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_environment_groups1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_environments1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_security_roles1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_service_principals1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_list_tenant_settings1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_query1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_register_application1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_reset_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_restore_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_self_elevate1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_set_backup_retention1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_set_governance_config1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_set_runtime_state1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_show_dlp_policy1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_unregister_application1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_admin_update_tenant_settings1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_analyze_flow_health1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_auth_who1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_backup_tenant2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / environments / items / additionalPropertiesRemoved value: -falsecs_bind_flow_connection1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_block_org_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_build_flow_definition9 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / definitionsAdded value: +{
+ "__schema0": {
+ "anyOf": [
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "description": "e.g. shared_office365 (cs_list_connectors)",
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "operationId": {
+ "description": "cs_describe_connector lists them",
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "connector",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "body": {},
+ "headers": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "http",
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "uri"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "compose",
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "type",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "initializeVariable",
+ "type": "string"
+ },
+ "value": {},
+ "valueType": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "setVariable",
+ "type": "string"
+ },
+ "value": {},
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "else": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "expression": {
+ "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "then": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "condition",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "expression",
+ "then"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "items": {
+ "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "foreach",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "items",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "scope",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "Succeeded",
+ "Failed",
+ "Cancelled"
+ ],
+ "type": "string"
+ },
+ "type": {
+ "const": "terminate",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "outputs": {
+ "items": {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "response",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "raw",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "json"
+ ],
+ "type": "object"
+ }
+ ]
+ }
+}Input schema / properties / outputs / items / $refRemoved value: -"#/properties/steps/items/anyOf/9/properties/outputs/items"Input schema / properties / outputs / items / propertiesAdded value: +{
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+}Input schema / properties / outputs / items / requiredAdded value: +[
+ "name"
+]Input schema / properties / outputs / items / typeAdded value: +"object"Input schema / properties / steps / items / $refAdded value: +"#/definitions/__schema0"Input schema / properties / steps / items / anyOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "description": "e.g. shared_office365 (cs_list_connectors)",
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "operationId": {
- "description": "cs_describe_connector lists them",
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "type": {
- "const": "connector",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {},
- "headers": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "http",
- "type": "string"
- },
- "uri": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "uri"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "compose",
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "initializeVariable",
- "type": "string"
- },
- "value": {},
- "valueType": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "setVariable",
- "type": "string"
- },
- "value": {},
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "else": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "expression": {
- "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "then": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "type": {
- "const": "condition",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "expression",
- "then"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "items": {
- "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "foreach",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "items",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "scope",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "message": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "status": {
- "enum": [
- "Succeeded",
- "Failed",
- "Cancelled"
- ],
- "type": "string"
- },
- "type": {
- "const": "terminate",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "outputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "type": {
- "const": "response",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "raw",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "json"
- ],
- "type": "object"
- }
-]Input schema / properties / trigger / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "required": {
- "type": "boolean"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "kind": {
- "const": "agent",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "manual",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "http",
- "type": "string"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "enum": [
- "Minute",
- "Hour",
- "Day",
- "Week",
- "Month"
- ],
- "type": "string"
- },
- "interval": {
- "type": "number"
- },
- "kind": {
- "const": "recurrence",
- "type": "string"
- },
- "startTime": {
- "type": "string"
- },
- "timeZone": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "frequency"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "type": "string"
- },
- "kind": {
- "const": "connector",
- "type": "string"
- },
- "operationId": {
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "recurrence": {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "type": "string"
- },
- "interval": {
- "type": "number"
- }
- },
- "required": [
- "frequency",
- "interval"
- ],
- "type": "object"
- }
- },
- "required": [
- "kind",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "kind": {
- "const": "raw",
- "type": "string"
- },
- "name": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "json"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "agent",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "http",
+ "type": "string"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "frequency": {
+ "enum": [
+ "Minute",
+ "Hour",
+ "Day",
+ "Week",
+ "Month"
+ ],
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ },
+ "kind": {
+ "const": "recurrence",
+ "type": "string"
+ },
+ "startTime": {
+ "type": "string"
+ },
+ "timeZone": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "frequency"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "connector",
+ "type": "string"
+ },
+ "operationId": {
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "recurrence": {
+ "properties": {
+ "frequency": {
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "frequency",
+ "interval"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "kind",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "kind": {
+ "const": "raw",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "json"
+ ],
+ "type": "object"
+ }
+]cs_chat1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_check_drift1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_check_solution2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / customEndpointAdded value: +{
+ "description": "Custom URL of the Power Apps Checker endpoint, instead of the geography's",
+ "type": "string"
+}cs_clone_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_clone_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_compare_environments2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / chain / items / additionalPropertiesRemoved value: -falsecs_compare_flow_runs1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_compare_snapshots1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_agent_from_template1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_auth_profile1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_connection1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_deployment_settings4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / connectionReferences / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / copilotAgents / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / environmentVariables / propertyNamesAdded value: +{
+ "type": "string"
+}cs_create_flow12 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / definitionsAdded value: +{
+ "__schema0": {
+ "anyOf": [
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "description": "e.g. shared_office365 (cs_list_connectors)",
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "operationId": {
+ "description": "cs_describe_connector lists them",
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "connector",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "body": {},
+ "headers": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "http",
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "uri"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "compose",
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "type",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "initializeVariable",
+ "type": "string"
+ },
+ "value": {},
+ "valueType": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "setVariable",
+ "type": "string"
+ },
+ "value": {},
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "else": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "expression": {
+ "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "then": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "condition",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "expression",
+ "then"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "items": {
+ "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "foreach",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "items",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "scope",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "Succeeded",
+ "Failed",
+ "Cancelled"
+ ],
+ "type": "string"
+ },
+ "type": {
+ "const": "terminate",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "outputs": {
+ "items": {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "response",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "raw",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "json"
+ ],
+ "type": "object"
+ }
+ ]
+ }
+}Input schema / properties / clientData / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / connectionReferences / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / definition / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / outputs / items / $refRemoved value: -"#/properties/steps/items/anyOf/9/properties/outputs/items"Input schema / properties / outputs / items / propertiesAdded value: +{
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+}Input schema / properties / outputs / items / requiredAdded value: +[
+ "name"
+]Input schema / properties / outputs / items / typeAdded value: +"object"Input schema / properties / steps / items / $refAdded value: +"#/definitions/__schema0"Input schema / properties / steps / items / anyOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "description": "e.g. shared_office365 (cs_list_connectors)",
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "operationId": {
- "description": "cs_describe_connector lists them",
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "type": {
- "const": "connector",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {},
- "headers": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "http",
- "type": "string"
- },
- "uri": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "uri"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "compose",
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "initializeVariable",
- "type": "string"
- },
- "value": {},
- "valueType": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "setVariable",
- "type": "string"
- },
- "value": {},
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "else": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "expression": {
- "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "then": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "type": {
- "const": "condition",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "expression",
- "then"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "items": {
- "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "foreach",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "items",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "scope",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "message": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "status": {
- "enum": [
- "Succeeded",
- "Failed",
- "Cancelled"
- ],
- "type": "string"
- },
- "type": {
- "const": "terminate",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "outputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "type": {
- "const": "response",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "raw",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "json"
- ],
- "type": "object"
- }
-]Input schema / properties / trigger / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "required": {
- "type": "boolean"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "kind": {
- "const": "agent",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "manual",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "http",
- "type": "string"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "enum": [
- "Minute",
- "Hour",
- "Day",
- "Week",
- "Month"
- ],
- "type": "string"
- },
- "interval": {
- "type": "number"
- },
- "kind": {
- "const": "recurrence",
- "type": "string"
- },
- "startTime": {
- "type": "string"
- },
- "timeZone": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "frequency"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "type": "string"
- },
- "kind": {
- "const": "connector",
- "type": "string"
- },
- "operationId": {
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "recurrence": {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "type": "string"
- },
- "interval": {
- "type": "number"
- }
- },
- "required": [
- "frequency",
- "interval"
- ],
- "type": "object"
- }
- },
- "required": [
- "kind",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "kind": {
- "const": "raw",
- "type": "string"
- },
- "name": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "json"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "agent",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "http",
+ "type": "string"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "frequency": {
+ "enum": [
+ "Minute",
+ "Hour",
+ "Day",
+ "Week",
+ "Month"
+ ],
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ },
+ "kind": {
+ "const": "recurrence",
+ "type": "string"
+ },
+ "startTime": {
+ "type": "string"
+ },
+ "timeZone": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "frequency"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "connector",
+ "type": "string"
+ },
+ "operationId": {
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "recurrence": {
+ "properties": {
+ "frequency": {
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "frequency",
+ "interval"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "kind",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "kind": {
+ "const": "raw",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "json"
+ ],
+ "type": "object"
+ }
+]cs_create_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_create_test_set_csv2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / cases / items / additionalPropertiesRemoved value: -falsecs_delete_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_delete_auth_profile1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_delete_connection1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_delete_flow1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_delete_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_deploy_pipeline1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_deploy_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_describe_connector1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_describe_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_describe_workspace1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_download_channel_manifestcs_download_evaluation_snapshotcs_edit_knowledge1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_edit_tool4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / addInputs / items / $refRemoved value: -"#/properties/setInputs/items"Input schema / properties / addInputs / items / anyOfAdded value: +[
+ {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "entity": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "automatic",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "shouldPromptUser": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "description"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "value": {
+ "description": "Literal or Power Fx (=System.User.Email)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / setInputs / items / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "type": "string"
- },
- "entity": {
- "type": "string"
- },
- "kind": {
- "const": "automatic",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "shouldPromptUser": {
- "type": "boolean"
- }
- },
- "required": [
- "kind",
- "name",
- "description"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "kind": {
- "const": "manual",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "value": {
- "description": "Literal or Power Fx (=System.User.Email)",
- "type": "string"
- }
- },
- "required": [
- "kind",
- "name",
- "value"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "entity": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "automatic",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "shouldPromptUser": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "description"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "value": {
+ "description": "Literal or Power Fx (=System.User.Email)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ }
+]cs_edit_topic6 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / definitionsAdded value: +{
+ "__schema0": {
+ "oneOf": [
+ {
+ "properties": {
+ "speak": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+ },
+ "text": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+ },
+ "type": {
+ "const": "message",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "allowInterruption": {
+ "type": "boolean"
+ },
+ "choices": {
+ "description": "Multiple-choice options (closed list) instead of an entity",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "entity": {
+ "enum": [
+ "String",
+ "Boolean",
+ "Number",
+ "Email",
+ "Date",
+ "DateTime",
+ "PhoneNumber",
+ "URL",
+ "Money",
+ "PersonName",
+ "City",
+ "CountryOrRegion",
+ "Organization",
+ "Percentage",
+ "Age",
+ "Duration",
+ "Color",
+ "Language",
+ "ZipCode",
+ "StreetAddress",
+ "File"
+ ],
+ "type": "string"
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "type": {
+ "const": "question",
+ "type": "string"
+ },
+ "variable": {
+ "description": "Topic.Name (prefix optional)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "prompt",
+ "variable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "cases": {
+ "items": {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "condition": {
+ "description": "Power Fx, e.g. Topic.Choice = \"Yes\"",
+ "type": "string"
+ }
+ },
+ "required": [
+ "condition",
+ "actions"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "else": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "condition",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "cases"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "replace": {
+ "type": "boolean"
+ },
+ "topic": {
+ "description": "Topic name or full reference",
+ "type": "string"
+ },
+ "type": {
+ "const": "redirect",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "topic"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "type": {
+ "const": "setVariable",
+ "type": "string"
+ },
+ "value": {
+ "type": [
+ "string",
+ "number",
+ "boolean"
+ ]
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "variable",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "autoSend": {
+ "type": "boolean"
+ },
+ "endIfAnswered": {
+ "type": "boolean"
+ },
+ "sources": {
+ "description": "Restrict to these knowledge sources (file stems from knowledge/, or full references)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "searchKnowledge",
+ "type": "string"
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "card": {
+ "anyOf": [
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "string"
+ }
+ ],
+ "description": "Adaptive Card JSON (object or string), version 1.5"
+ },
+ "outputTypes": {
+ "additionalProperties": {
+ "enum": [
+ "String",
+ "Number",
+ "Boolean"
+ ],
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "outputs": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Input card: card field id -> Topic variable; omit for a display-only card",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "card",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "card"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "message": {
+ "description": "Message to the human agent",
+ "type": "string"
+ },
+ "phoneNumber": {
+ "description": "Transfer to a phone number instead of an agent",
+ "type": "string"
+ },
+ "type": {
+ "const": "transfer",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "type": {
+ "const": "endConversation",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "body": {},
+ "headers": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "method": {
+ "enum": [
+ "Get",
+ "Post",
+ "Put",
+ "Patch",
+ "Delete"
+ ],
+ "type": "string"
+ },
+ "responseVariable": {
+ "type": "string"
+ },
+ "type": {
+ "const": "http",
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "responseVariable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "flowId": {
+ "type": "string"
+ },
+ "input": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "invokeFlow",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "flowId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "clearTopicQueue": {
+ "type": "boolean"
+ },
+ "type": {
+ "const": "end",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "node": {
+ "additionalProperties": {},
+ "description": "A full DialogAction node; 'id' is added if missing",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "raw",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "node"
+ ],
+ "type": "object"
+ }
+ ]
+ }
+}Input schema / properties / appendActions / items / $refAdded value: +"#/definitions/__schema0"Input schema / properties / appendActions / items / anyOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "speak": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- },
- "text": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- },
- "type": {
- "const": "message",
- "type": "string"
- }
- },
- "required": [
- "type",
- "text"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "allowInterruption": {
- "type": "boolean"
- },
- "choices": {
- "description": "Multiple-choice options (closed list) instead of an entity",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "entity": {
- "enum": [
- "String",
- "Boolean",
- "Number",
- "Email",
- "Date",
- "DateTime",
- "PhoneNumber",
- "URL",
- "Money",
- "PersonName",
- "City",
- "CountryOrRegion",
- "Organization",
- "Percentage",
- "Age",
- "Duration",
- "Color",
- "Language",
- "ZipCode",
- "StreetAddress",
- "File"
- ],
- "type": "string"
- },
- "prompt": {
- "type": "string"
- },
- "type": {
- "const": "question",
- "type": "string"
- },
- "variable": {
- "description": "Topic.Name (prefix optional)",
- "type": "string"
- }
- },
- "required": [
- "type",
- "prompt",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "cases": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/appendActions/items"
- },
- "type": "array"
- },
- "condition": {
- "description": "Power Fx, e.g. Topic.Choice = \"Yes\"",
- "type": "string"
- }
- },
- "required": [
- "condition",
- "actions"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "else": {
- "items": {
- "$ref": "#/properties/appendActions/items"
- },
- "type": "array"
- },
- "type": {
- "const": "condition",
- "type": "string"
- }
- },
- "required": [
- "type",
- "cases"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "replace": {
- "type": "boolean"
- },
- "topic": {
- "description": "Topic name or full reference",
- "type": "string"
- },
- "type": {
- "const": "redirect",
- "type": "string"
- }
- },
- "required": [
- "type",
- "topic"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "type": {
- "const": "setVariable",
- "type": "string"
- },
- "value": {
- "type": [
- "string",
- "number",
- "boolean"
- ]
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "variable",
- "value"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "autoSend": {
- "type": "boolean"
- },
- "endIfAnswered": {
- "type": "boolean"
- },
- "sources": {
- "description": "Restrict to these knowledge sources (file stems from knowledge/, or full references)",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "type": {
- "const": "searchKnowledge",
- "type": "string"
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "card": {
- "anyOf": [
- {
- "additionalProperties": {},
- "type": "object"
- },
- {
- "type": "string"
- }
- ],
- "description": "Adaptive Card JSON (object or string), version 1.5"
- },
- "outputTypes": {
- "additionalProperties": {
- "enum": [
- "String",
- "Number",
- "Boolean"
- ],
- "type": "string"
- },
- "type": "object"
- },
- "outputs": {
- "additionalProperties": {
- "type": "string"
- },
- "description": "Input card: card field id -> Topic variable; omit for a display-only card",
- "type": "object"
- },
- "type": {
- "const": "card",
- "type": "string"
- }
- },
- "required": [
- "type",
- "card"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "message": {
- "description": "Message to the human agent",
- "type": "string"
- },
- "phoneNumber": {
- "description": "Transfer to a phone number instead of an agent",
- "type": "string"
- },
- "type": {
- "const": "transfer",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "type": {
- "const": "endConversation",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {},
- "headers": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "method": {
- "enum": [
- "Get",
- "Post",
- "Put",
- "Patch",
- "Delete"
- ],
- "type": "string"
- },
- "responseVariable": {
- "type": "string"
- },
- "type": {
- "const": "http",
- "type": "string"
- },
- "url": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "url",
- "responseVariable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "flowId": {
- "type": "string"
- },
- "input": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "output": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "type": {
- "const": "invokeFlow",
- "type": "string"
- }
- },
- "required": [
- "type",
- "flowId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "clearTopicQueue": {
- "type": "boolean"
- },
- "type": {
- "const": "end",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "node": {
- "additionalProperties": {},
- "description": "A full DialogAction node; 'id' is added if missing",
- "type": "object"
- },
- "type": {
- "const": "raw",
- "type": "string"
- }
- },
- "required": [
- "type",
- "node"
- ],
- "type": "object"
- }
-]Input schema / properties / insertActions / additionalPropertiesRemoved value: -falseInput schema / properties / insertActions / properties / actions / items / $refPrevious value: -"#/properties/appendActions/items"New value: +"#/definitions/__schema0"cs_env_fetch1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_env_list1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_env_select1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_env_who1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_explain_flow_run1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_extract_agent_template1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_extract_translations1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_generate_instructions1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_get_connector_consent_bypasscs_get_evaluation_run1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_get_flow1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_get_flow_run1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_get_org_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_get_test_setcs_get_transcript1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_guide1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_import_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_init1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_init_solution_project1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_job_status1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_agents1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_connections1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_connectors1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_environments1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_evaluation_runs1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_flow_runs1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_flows1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_org_agents1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_pipelines1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_prompts1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_solutions1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_test_sets1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_list_transcripts1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_login1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_login_status1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_logout1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_lookup_schema1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_merge_translations1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_pac1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_pack1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_pack_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_publish1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_publish_customizations1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_pull1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_pull_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_push1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_quarantine_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_reassign_agent_ownercs_reassign_org_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_remove_component1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_review_agent1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_run_conversation_tests3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / tests / items / additionalPropertiesRemoved value: -falseInput schema / properties / tests / items / properties / expect / propertyNamesAdded value: +{
+ "type": "string"
+}cs_run_evaluation3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / mcsConnectionId / descriptionPrevious value: -"User profile connection id for authenticated knowledge/tools"New value: +"Copilot Studio connection id of the user profile to run as; omit for an anonymous run. Power Automate > Connections > Microsoft Copilot Studio, the GUID in the URL"Input schema / properties / toolsConnectionsAdded value: +{
+ "description": "Which connection each connector tool should use during the run",
+ "items": {
+ "properties": {
+ "botId": {
+ "description": "Dataverse bot id; default: the evaluated agent",
+ "type": "string"
+ },
+ "botSchemaName": {
+ "type": "string"
+ },
+ "connections": {
+ "items": {
+ "properties": {
+ "connectionId": {
+ "description": "The user connection to run it with (cs_list_connections)",
+ "type": "string"
+ },
+ "connectionReferenceName": {
+ "description": "Connection reference name in the agent, when the tool is bound through one",
+ "type": "string"
+ },
+ "connectorId": {
+ "description": "Connector id, e.g. shared_office365 (cs_list_connectors)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "connectorId",
+ "connectionId"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "connections"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}cs_run_flow2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / payload / propertyNamesAdded value: +{
+ "type": "string"
+}cs_select_auth_profile1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_set_connector_consent_bypasscs_set_flow_state1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_set_solution_version1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_set_tool_preset1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_snapshot_environment1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_solution_online_version1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_status1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_summarize_transcripts1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_sync_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_test_set_from_transcripts1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_update_agent4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / addConversationStarters / items / additionalPropertiesRemoved value: -falseInput schema / properties / capabilities / additionalPropertiesRemoved value: -falseInput schema / properties / conversationStarters / items / additionalPropertiesRemoved value: -falsecs_update_connection1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_update_flow12 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / definitionsAdded value: +{
+ "__schema0": {
+ "anyOf": [
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "description": "e.g. shared_office365 (cs_list_connectors)",
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "operationId": {
+ "description": "cs_describe_connector lists them",
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "type": {
+ "const": "connector",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "body": {},
+ "headers": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "http",
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "uri"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "compose",
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "type",
+ "name",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "initializeVariable",
+ "type": "string"
+ },
+ "value": {},
+ "valueType": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "setVariable",
+ "type": "string"
+ },
+ "value": {},
+ "variable": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "variable",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "else": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "expression": {
+ "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "then": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "condition",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "expression",
+ "then"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "items": {
+ "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "foreach",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "items",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "actions": {
+ "items": {
+ "$ref": "#/definitions/__schema0"
+ },
+ "type": "array"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "scope",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "actions"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "message": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "Succeeded",
+ "Failed",
+ "Cancelled"
+ ],
+ "type": "string"
+ },
+ "type": {
+ "const": "terminate",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "outputs": {
+ "items": {
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "type": {
+ "const": "response",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "const": "raw",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "json"
+ ],
+ "type": "object"
+ }
+ ]
+ }
+}Input schema / properties / clientData / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / connectionReferences / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / definition / propertyNamesAdded value: +{
+ "type": "string"
+}Input schema / properties / outputs / items / $refRemoved value: -"#/properties/steps/items/anyOf/9/properties/outputs/items"Input schema / properties / outputs / items / propertiesAdded value: +{
+ "name": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ },
+ "value": {}
+}Input schema / properties / outputs / items / requiredAdded value: +[
+ "name"
+]Input schema / properties / outputs / items / typeAdded value: +"object"Input schema / properties / steps / items / $refAdded value: +"#/definitions/__schema0"Input schema / properties / steps / items / anyOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "description": "e.g. shared_office365 (cs_list_connectors)",
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "operationId": {
- "description": "cs_describe_connector lists them",
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "type": {
- "const": "connector",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {},
- "headers": {
- "additionalProperties": {
- "type": "string"
- },
- "type": "object"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "http",
- "type": "string"
- },
- "uri": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "uri"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "compose",
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "initializeVariable",
- "type": "string"
- },
- "value": {},
- "valueType": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "const": "setVariable",
- "type": "string"
- },
- "value": {},
- "variable": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "variable"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "else": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "expression": {
- "description": "Logic Apps expression, e.g. @equals(triggerBody()?['status'],'open')",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "then": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "type": {
- "const": "condition",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "expression",
- "then"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "items": {
- "description": "Expression yielding the collection, e.g. @body('List_rows')?['value']",
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "foreach",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "items",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "actions": {
- "items": {
- "$ref": "#/properties/steps/items"
- },
- "type": "array"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "scope",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "actions"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "message": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "status": {
- "enum": [
- "Succeeded",
- "Failed",
- "Cancelled"
- ],
- "type": "string"
- },
- "type": {
- "const": "terminate",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "outputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "name": {
- "type": "string"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- },
- "value": {}
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "type": {
- "const": "response",
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "const": "raw",
- "type": "string"
- }
- },
- "required": [
- "type",
- "name",
- "json"
- ],
- "type": "object"
- }
-]Input schema / properties / trigger / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "description": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "required": {
- "type": "boolean"
- },
- "type": {
- "enum": [
- "string",
- "number",
- "boolean",
- "object",
- "array"
- ],
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "kind": {
- "const": "agent",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "manual",
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "inputs": {
- "items": {
- "$ref": "#/properties/trigger/anyOf/0/properties/inputs/items"
- },
- "type": "array"
- },
- "kind": {
- "const": "http",
- "type": "string"
- },
- "method": {
- "enum": [
- "GET",
- "POST",
- "PUT",
- "PATCH",
- "DELETE"
- ],
- "type": "string"
- }
- },
- "required": [
- "kind"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "enum": [
- "Minute",
- "Hour",
- "Day",
- "Week",
- "Month"
- ],
- "type": "string"
- },
- "interval": {
- "type": "number"
- },
- "kind": {
- "const": "recurrence",
- "type": "string"
- },
- "startTime": {
- "type": "string"
- },
- "timeZone": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "frequency"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "connectionReference": {
- "type": "string"
- },
- "connectorId": {
- "type": "string"
- },
- "kind": {
- "const": "connector",
- "type": "string"
- },
- "operationId": {
- "type": "string"
- },
- "parameters": {
- "additionalProperties": {},
- "type": "object"
- },
- "recurrence": {
- "additionalProperties": false,
- "properties": {
- "frequency": {
- "type": "string"
- },
- "interval": {
- "type": "number"
- }
- },
- "required": [
- "frequency",
- "interval"
- ],
- "type": "object"
- }
- },
- "required": [
- "kind",
- "connectorId",
- "operationId"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "json": {
- "additionalProperties": {},
- "type": "object"
- },
- "kind": {
- "const": "raw",
- "type": "string"
- },
- "name": {
- "type": "string"
- }
- },
- "required": [
- "kind",
- "json"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "agent",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "manual",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "inputs": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "type": {
+ "enum": [
+ "string",
+ "number",
+ "boolean",
+ "object",
+ "array"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "const": "http",
+ "type": "string"
+ },
+ "method": {
+ "enum": [
+ "GET",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "frequency": {
+ "enum": [
+ "Minute",
+ "Hour",
+ "Day",
+ "Week",
+ "Month"
+ ],
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ },
+ "kind": {
+ "const": "recurrence",
+ "type": "string"
+ },
+ "startTime": {
+ "type": "string"
+ },
+ "timeZone": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "frequency"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "connectionReference": {
+ "type": "string"
+ },
+ "connectorId": {
+ "type": "string"
+ },
+ "kind": {
+ "const": "connector",
+ "type": "string"
+ },
+ "operationId": {
+ "type": "string"
+ },
+ "parameters": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "recurrence": {
+ "properties": {
+ "frequency": {
+ "type": "string"
+ },
+ "interval": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "frequency",
+ "interval"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "kind",
+ "connectorId",
+ "operationId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "json": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "kind": {
+ "const": "raw",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "json"
+ ],
+ "type": "object"
+ }
+]cs_update_settings2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / patch / propertyNamesAdded value: +{
+ "type": "string"
+}cs_upgrade_solution1 field changedInput schema / additionalPropertiesRemoved value: -falsecs_validate1 field changedInput schema / additionalPropertiesRemoved value: -falsev0.1.7cs_add_flow1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_add_knowledge_source1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_add_tool1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_add_topic1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_add_trigger1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_add_variable1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_create_agent4 fields changedInput schema / properties / backgroundAdded value: +{
+ "description": "Run in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled.",
+ "type": "boolean"
+}Input schema / properties / projectDir / descriptionPrevious value: -"Target directory (must be empty or not exist)"New value: +"Folder for the agent's files, new or empty. Omit it to be offered one named after the agent."Input schema / properties / publisherPrefix / descriptionPrevious value: -"Solution publisher prefix, e.g. contoso; must match the publisher of an existing target solution"New value: +"Publisher prefix, 2-8 lowercase letters or digits: it becomes part of every component's schema name and must match the publisher of the solution the agent lands in. Omit it to be shown the publishers in the environment and what the choice decides."Input schema / requiredPrevious value: -[
- "name",
- "publisherPrefix",
- "projectDir"
-]New value: +[
+ "name"
+]cs_edit_knowledge1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_edit_tool1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_edit_topic1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_generate_instructions2 fields changedInput schema / properties / apply / descriptionPrevious value: -"Write the result into the agent instructions"New value: +"Write the result into the agent instructions (needs confirm: true as well)"Input schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}cs_update_agent3 fields changedInput schema / properties / appendResponseInstructions / descriptionAdded value: +"Add a line to the response formatting, within the same 500 characters"Input schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}Input schema / properties / responseInstructions / descriptionPrevious value: -"How answers should be worded and formatted (the portal's response instructions), separate from the main instructions"New value: +"How answers should be worded and formatted (Settings > Responses > Response formatting in the portal), separate from the main instructions. Capped at 500 characters."cs_update_settings1 field changedInput schema / properties / confirmAdded value: +{
+ "description": "Required to write the change to the file. Without it the tool returns a preview - the changed lines against the current ones, and the character count - and writes nothing.",
+ "type": "boolean"
+}v0.1.6cs_analyze_flow_healthcs_bind_flow_connectioncs_compare_flow_runscs_delete_flowcs_explain_flow_runcs_guide1 field changedInput schema / properties / topic / enumPrevious value: -[
- "getting-started",
- "instructions",
- "knowledge",
- "tools",
- "topics",
- "evaluations",
- "publish-and-test",
- "drift",
- "transcripts",
- "solutions",
- "administration",
- "troubleshooting"
-]New value: +[
+ "getting-started",
+ "instructions",
+ "knowledge",
+ "tools",
+ "topics",
+ "flows",
+ "evaluations",
+ "publish-and-test",
+ "drift",
+ "transcripts",
+ "solutions",
+ "administration",
+ "troubleshooting"
+]v0.1.5cs_add_flowcs_add_knowledge_sourcecs_add_solution_componentcs_add_solution_licensecs_add_solution_referencecs_add_toolcs_add_topiccs_add_triggercs_add_variablecs_admin_add_environment_to_groupcs_admin_assign_groupcs_admin_assign_usercs_admin_assign_userscs_admin_backup_environmentcs_admin_copy_environmentcs_admin_create_environmentcs_admin_create_service_principalcs_admin_delete_environmentcs_admin_environment_statuscs_admin_list_app_templatescs_admin_list_applicationscs_admin_list_backupscs_admin_list_dlp_policiescs_admin_list_environment_groupscs_admin_list_environmentscs_admin_list_security_rolescs_admin_list_service_principalscs_admin_list_tenant_settingscs_admin_querycs_admin_register_applicationcs_admin_reset_environmentcs_admin_restore_environmentcs_admin_self_elevatecs_admin_set_backup_retentioncs_admin_set_governance_configcs_admin_set_runtime_statecs_admin_show_dlp_policycs_admin_unregister_applicationcs_admin_update_tenant_settingscs_auth_whocs_backup_tenantcs_block_org_agentcs_build_flow_definitioncs_chatcs_check_driftcs_check_solutioncs_clone_agentcs_clone_solutioncs_compare_environmentscs_compare_snapshotscs_create_agentcs_create_agent_from_templatecs_create_auth_profilecs_create_connectioncs_create_deployment_settingscs_create_flowcs_create_solutioncs_create_test_set_csvcs_delete_agentcs_delete_auth_profilecs_delete_connectioncs_delete_solutioncs_deploy_pipelinecs_deploy_solutioncs_describe_connectorcs_describe_solutioncs_describe_workspacecs_edit_knowledgecs_edit_toolcs_edit_topiccs_env_fetchcs_env_listcs_env_selectcs_env_whocs_extract_agent_templatecs_extract_translationscs_generate_instructionscs_get_evaluation_runcs_get_flowcs_get_flow_runcs_get_org_agentcs_get_transcriptcs_guidecs_import_solutioncs_initcs_init_solution_projectcs_job_statuscs_list_agentscs_list_auth_profilescs_list_connectionscs_list_connectorscs_list_environmentscs_list_evaluation_runscs_list_flow_runscs_list_flowscs_list_org_agentscs_list_pipelinescs_list_promptscs_list_solutionscs_list_test_setscs_list_transcriptscs_logincs_login_statuscs_logoutcs_lookup_schemacs_merge_translationscs_paccs_packcs_pack_solutioncs_publishcs_publish_customizationscs_pullcs_pull_solutioncs_pushcs_quarantine_agentcs_reassign_org_agentcs_remove_componentcs_review_agentcs_run_conversation_testscs_run_evaluationcs_run_flowcs_select_auth_profilecs_set_flow_statecs_set_solution_versioncs_set_tool_presetcs_snapshot_environmentcs_solution_online_versioncs_statuscs_summarize_transcriptscs_sync_solutioncs_test_set_from_transcriptscs_update_agentcs_update_connectioncs_update_flowcs_update_settingscs_upgrade_solutioncs_validateScored across 148 tools
Descriptions are unusually thorough and explicitly cross-reference siblings (e.g. cs_list_flow_runs vs cs_get_flow vs cs_explain_flow_run, cs_pull vs cs_publish), which resolves most confusion. However, with 148 tools there are several genuinely close pairs an agent could misselect: cs_list_environments / cs_env_list / cs_admin_list_environments, cs_list_agents / cs_list_org_agents, cs_reassign_agent_owner / cs_reassign_org_agent, cs_deploy_solution / cs_deploy_pipeline, and cs_admin_assign_user / cs_admin_assign_users / cs_admin_assign_group.
Every tool uses the uniform cs_ prefix with snake_case and a near-consistent verb_noun or verb_noun_qualifier pattern (cs_create_agent, cs_list_flows, cs_delete_flow, cs_admin_create_environment). The namespace grouping by domain (cs_admin_*, cs_solution_*, cs_flow_*) is predictable and readable.
148 tools is a severe overload for any single server; the server itself concedes this by shipping cs_set_tool_preset to hide ~50k tokens of schema because the full list crowds a model's context and degrades selection. This is exactly the extreme-mismatch case the rubric flags at 50+ tools.
Coverage is exceptional across the whole lifecycle: agent authoring/editing, knowledge, tools, flows, connections, solutions, pipelines, publishing, drift, evaluations, transcripts, and full tenant administration with backup/restore/governance. Almost no dead ends exist; the gaps are portal-only actions that are explicitly called out as such.
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
Git-backed platform for skills, tools, and context for AI agents
