security-preflight__describe_agent

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

No annotations are provided, so the description carries the full burden. It states the sections it reports (scope, evidence boundary, inputs, outputs) but says nothing about whether the call is a pure read, whether it hits the network, latency, or whether the response is a manifest static snapshot versus live state. For a zero-annotation tool this is thin.

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?

It is a single short sentence, which is efficient, but the bracketed subsystem tag consumes most of the line and the actual payload information is a bare list. Front-loading is fine; the content density is low.

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?

No output schema exists, so the description must explain what comes back — it gestures at 'scope, evidence boundary, inputs, outputs' but does not say what form that takes, how it can be used by the calling agent, or the difference between the static manifest and the runtime checks. Given no annotations, no params, no output schema, this is under-specified.

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?

There are zero parameters, so the baseline of 4 applies. The description cannot and need not add parameter meaning; nothing is missing here.

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 says it will 'Describe scope, evidence boundary, inputs, and outputs' — that's the operation, but it never says what this agent IS (a preflight security-checking agent). It restates the tool name's meta-purpose without identifying the resource under description, and it never distinguishes itself from the many other 'describe_agent' siblings in this namespace.

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?

No when-to-use or when-not-to-use guidance at all. In a fleet containing ~15 identically-named 'describe_agent' tools across different namespaces, there is nothing telling the agent why this one should be called over security_preflight, scan_source, or screen_injection.

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