build-identity-graph

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

With no annotations the description carries the full burden and delivers real behavioral context: findings are 'observations, not verdicts,' service accounts are classified separately from interactive ones for a stated reason, and edges are capped/ranked. It still omits any auth/permission or rate-limit notes, but for an analysis/read tool the disclosure is substantial.

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 purpose in the first clause, then layers interpretation guidance. Dense with no filler, though the run-on construction packs several distinct ideas into long sentences that could be segmented for faster scanning.

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 10-parameter tool with no output schema, the description gives a conceptual picture of the return (ranked findings, identity/workload/destination rollups, capped edges) and explains the interpretation caveats. Sufficient for correct invocation; only permissions and pagination specifics are absent.

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 coverage is 100%, so the baseline is 3. The description adds conceptual meaning beyond the schema: why domain-qualified and bare identities collapse to one identity, and why service accounts matter to interpretation (wide host spread normal for daemons, notable for people) — interpretive value the schema fields do not carry.

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?

Names a specific verb+resource (build an identity-centric traffic graph) and enumerates exactly what it exposes: which account ran a process, from which workloads, to what, over what period. It explicitly distinguishes its angle from workload-label tools ('questions that workload labels cannot'), so an agent can tell it apart from get-workloads without opening schemas.

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?

Gives clear context for when to reach for it: least-privilege questions about what an account can reach and from how many places, plus identity resolution and service-account separation. It contrasts with label-based approaches but never names a specific alternative sibling or a when-not condition, so use is strongly implied rather than fully routed.

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