identity_360

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the description's job is to add context. It adds useful behavioral scope: the tool aggregates Entra + Azure access via direct/group/PIM, traces how access was received, and includes ownership and risk findings. It does not describe output structure or potential volume, but the annotations lower the burden for safety-related traits.

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 compact and front-loads the primary concept ('visão completa de uma identidade') before enumerating covered dimensions. Each clause adds distinct information: access types, provenance, ownership, risk, and accepted identifiers. Slightly repetitive with the tool name at the start, but otherwise efficient.

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 high-complexity aggregation tool with no output schema, the description gives a solid category-level map of what to expect: identity basics, Entra/Azure access, assignment reasoning, ownership, and risk. It also identifies accepted input formats. It could be more explicit about the shape of findings or whether output is a single summary object versus multiple sections, but the core information is present.

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 schema only provides user_identifier as a required string with no description, and schema coverage is 0%. The description compensates by specifying that UPN, displayName, or objectId are all accepted, which is essential for calling the tool correctly. It does not give an explicit example or clarify uniqueness/case behavior, but it provides the core semantic guidance.

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 defines identity_360 as a complete view of an identity, listing its scope: identity attributes, Entra/Azure access (direct/group/PIM), access origin, ownership, and risk. It clearly identifies the resource (an identity) and distinguishes it from narrower sibling tools. It lacks an explicit verb such as "returns" or "provides," so it stops short of a perfect 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 description conveys that the tool is appropriate when a holistic identity perspective is needed, including access, ownership, and risk. It does not explicitly state when to prefer this over siblings like get_user_effective_azure_access or compute_identity_blast_radius, nor does it mention exclusions. The usage context is implied rather than made explicit.

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