powerplatform_api_call

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

With no annotations present, the description carries the full burden of behavioral disclosure, but it only says to execute a call and consult documentation first. It does not mention authentication requirements, side effects of mutating methods, error behavior, rate limits, or that the tool is a raw passthrough whose behavior depends entirely on the chosen endpoint.

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

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

The description is short and front-loaded with the core action, and both sentences serve a purpose. It loses a point because 'relevant resource documentation' is somewhat vague and the overall definition is thin for a tool that delegates to a large API surface.

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 API execution tool with no output schema and no annotations, the instruction to read the skill and resource documentation first is a useful mitigation, but the description still lacks direct context about return values, permission expectations, or the range of Power Platform APIs it can reach. It is adequate but leaves meaningful gaps for the agent to discover elsewhere.

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 method, endpoint, body, and environment_id. The description adds no parameter-level meaning, but it does not need to; the baseline of 3 is appropriate when the schema carries the parametric load.

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

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

The description clearly identifies the action as executing a Power Platform API call, which distinguishes it from the sibling graph_api_call tool by platform. It also directs the agent to first read the powerplatform-api skill, reinforcing what the tool targets. It stops short of a 5 because it does not explicitly contrast itself with graph_api_call or describe its generic low-level passthrough nature.

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 only guidance offered is 'Read the powerplatform-api skill and relevant resource documentation first,' which is a prerequisite instruction rather than a usage-selection rule. It does not say when to use this tool instead of graph_api_call, list_skills, or read_skill, nor does it describe contexts where the tool is appropriate or inappropriate.

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