bing_plan_add_site_roles

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

Annotations only declare write/non-idempotent/open-world, but the description adds critical semantics: no change is sent to Bing, it records intent only, it may consume quota, and the agent must not claim the change was applied and instead must surface the plan id and CLI apply command. This is exactly the behavior an agent needs and cannot get from structured fields.

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 short sentences, each with a distinct job: purpose, when to use, two exclusions, side-effect profile, and required output behavior. Purpose and routing are front-loaded; 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?

Behavior, side effects, and expected output are covered, which is strong for a plan-recording tool with no output schema. However, with six fully undocumented required parameters, an agent still cannot know what to supply for authentication_code or delegated_url, leaving the definition incomplete for 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?

All six required parameters have 0% schema description coverage, so the description carries the full burden, yet it never explains authentication_code, delegated_url, or the is_administrator/is_read_only distinction. Only 'one email address' implicitly points at user_email. With a 6-param required-only schema and no coverage, this is a significant 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 ('Record a plan to delegate access to a Bing Webmaster site for one email address') and immediately distinguishes itself from the read-only sibling bing_site_roles and the inverse sibling bing_plan_remove_site_role. An agent can select this tool 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?

Explicit when-to-use ('when the user wants access granted and a person must review the delegation first') plus two explicit when-not-to-use clauses that name the correct alternative tools. Nothing is left to inference about routing.

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