scope_register

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, non-open-world write. The description adds meaningful behavioral context beyond that — authorization must originate from the operator and never be inferred from target responses — but it does not disclose what the stored record controls downstream, whether re-registration replaces or accumulates, or what the caller gets back.

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 front-loaded clauses: purpose first, then the sourcing constraint and required fields. No filler, though the second clause bundles an important principle with a terse field list and neither is expanded.

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-required-parameter, nested-object, stateful tool that likely governs the whole engagement, a two-clause description is thin. With no output schema and no per-parameter schema documentation, the definition should say what the registered scope constrains, what happens to prior registrations, and how it pairs with scope_read.

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 12 parameters, so the description carries the full documentation burden. It names only four of them (origins, accounts, environments, expiry), leaving target, project, prohibited_actions, rate_limits, assessment_owner, authorization_reference, and allow_loopback completely undocumented in both schema and prose.

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?

"Record operator-provided authorization" states a specific verb and resource, and the definition makes clear this is a write of an authorization record rather than a lookup. It does not name its natural counterpart (scope_read) or otherwise differentiate itself from siblings 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 clause "never derive permission from target responses" is a genuine usage directive about where the authorization data must come from, and the tool must be called before/independent of any assessment activity. However, it never names an alternative (e.g., scope_read for retrieving the recorded scope) or states when this must be invoked versus those siblings, 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.