List agents

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It does add meaningful behavior about auth prerequisites: 'needs a pac auth profile' and 'queries the bots table with the MSAL token', plus the default auto fallback. It does not explicitly state that the operation is read-only, although the verb 'list' implies it, and it misses behavior such as whether it returns the full agent list or paginated 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?

The description is very short and to-the-point. The main action is fronted, and the two subsequent sentences each add one relevant piece of context (modes, default behavior). There is no redundancy, and the run-on grammar is minor.

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 is insufficient contextually. It covers the via modes but leaves several important parameters (ownerOnly, dataverseUrl) without explanation, and does not describe the return contract such as whether an empty list versus an error comes back. An agent would need to inspect or guess the details of the 'dataverse' query 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 57%, so the description is expected to contribute meaning beyond the schema. It does add semantics for the 'via' parameter by explaining what ends with auto/pack/dataverse, its default fallback, and the underlying command or data source. Yet parameters like 'ownerOnly', 'dataverseUrl' are left unexplained both in schema and description, 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 opens with a specific action and object, 'List Copilot Studio agents in an environment,' and the phrase 'in an environment' differentiates it from environment-agnostic siblings such as cs_list_org_agents. It does not name a sibling explicitly, but the resource and scope are enough to distinguish it from list_flows or list_agents tools.

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

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

The description gives concrete when-to-use guidance for the 'via' execution modes: 'pac' uses pac copilot list, 'dataverse' queries the bots table, and 'auto' selects pac first. However, it never contrasts with alternative list tools or says when not to use this tool over, for instance, cs_list_org_agents, so usage 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.