Execute Authorized Tool

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

Annotations already declare destructiveHint, readOnlyHint=false, and openWorldHint, so the safety profile is partly covered. The description adds genuinely useful context beyond them: rechecks for App Roles, confirmation policy, audit, and Graph scope controls, plus the failure behavior ('invalid parameters return the expected schema'). It does not describe what specifically gets destroyed on a mutating call, 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-loads the core verb and object in the first sentence, then layers workflow, security behavior, and error handling. The trailing Chinese intent keywords are extra bulk but serve a legitimate multilingual routing purpose, so the structure is efficient overall.

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 is not obligated to explain returns, and it covers purpose, prerequisites, re-validation behavior, and error signaling. For a generic gateway executor with a nested, free-form parameters object, the coverage is solid though it says nothing about execution scope limits or success 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 100%, so both parameters (toolName and parameters) are already documented in the schema, giving a baseline of 3. The description reinforces the relationship between 'parameters' and the target tool's inputSchema but adds no format, syntax, or constraint 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 (Execute) and resource (a tool returned by gateway_search_tools), and explicitly anchors the tool within the search→schema→execute chain that distinguishes it from gateway_search_tools and gateway_get_tool_schema. An agent can immediately tell what this does and how it differs from its 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?

Names the prerequisite producer (gateway_search_tools) and the parameter source ('matching its inputSchema' / gateway_get_tool_schema), so the intended workflow is clear. It stops short of explicit when-not-to-use guidance or naming confirm_execute as an alternative, so it is not a full 5.

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