get_permission_context

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

With no annotations, the description carries full burden for behavioral disclosure. It explicitly states that it does NOT rank or compute least privilege automatically, explains why resource count and ownership scoping are different axes, and warns that role-permission cross-referencing is heuristic and not ground truth. This gives the agent a realistic model of the tool's capabilities and limitations.

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 information-dense but efficiently structured, opening with 'Two modes' and then detailing each mode and relevant caveats. Every sentence contributes value, including the anti-goal clarification about least privilege and the heuristic caveat. It is long but not wasteful, and front-loaded with the most important usage differentiator.

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?

Given the tool's complexity and lack of output schema, the description is remarkably complete. It describes what each mode returns, the fields used for reasoning, the notion of ownership scoping, and important failure modes (heuristic correlation). It even clarifies that the tool does not decide for the user, which sets expectations for downstream reasoning. The only minor gap is not detailing the behavior of 'recent changes', but this is not critical to selecting/invoking the tool.

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?

The description adds meaningful context beyond the schema by explaining how object_name and permission_name mode switch, and what is_ownership_scoped means in the output. It does not elaborate on limit or endpoint, but limit has a schema description and endpoint is an enum. The addition clarifies the relationship between parameters and the output semantics, so it goes beyond the baseline of 3.

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 states the tool's function with specific verbs: it lists permissions touching a Graph object, what each unlocks, who can grant them, and recent changes. It also details the second mode for comparing a permission's detail with overlapping alternatives. This is distinct from sibling tools focused on history, schema, or change snapshots.

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 provides clear context for when to use each mode, including a concrete example comparing a less-privileged alternative. It implies when to use the tool (for permission analysis) and hints at limitations (does not rank or claim to compute least privilege). However, it does not explicitly name alternatives or exclusions relative to sibling tools, so it stops short of full usage guidance.

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