get_project_context

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states no plaintext secret values are ever returned, the return is pretty-printed JSON, and the shape is intentionally broad and may grow, advising defensive reading. It doesn't cover access/auth requirements or rate limits, keeping it short of a 5.

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 front-loaded with the core purpose, then usage, then safety, then return shape. It is dense but each sentence carries distinct information. It runs slightly long with the enumeration of snapshot contents, but nothing is redundant.

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 read-only, no-output-schema, zero-required-param aggregate tool, the description covers purpose, usage routing, exclusions, safety guarantees, and return-shape expectations. An agent has everything needed to call it correctly and interpret the response defensively.

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 schema already documents every parameter with examples, enums, and scope-dependency rules. The description adds no parameter-level detail, so baseline would be 3; it earns a 4 only because it establishes the session-orientation frame and value-safety scope that give the parameters their intended context.

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 opens with a specific verb-resource pair ('Return a single redacted snapshot') and enumerates the exact contents (secrets present, detected env, manifest declarations, providers, hooks, audit activity). It explicitly distinguishes itself from siblings list_secrets, check_project, and audit_log, so an agent can route correctly without inspecting 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?

It states the precise usage condition ('Use this as the very first call in a session to orient the agent') and gives three named alternatives with the condition that selects each. There is no ambiguity about when this tool is preferred over the alternatives.

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