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

The annotations already mark the tool read-only and idempotent, and the description adds genuinely useful behavioral context: the verdict is deterministic, the thresholds are combined with IFF semantics, defaults are specified (85 and 8000), and the edge behavior contains a notable limitation about hold-hints not listing empty slots. This is meaningful operational detail beyond what annotations provide.

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 dense: phase label, resource, purpose, threshold rule, defaults, and edge caveat all fit into a few sentences with no filler. The most important decision logic appears early, which helps an agent parse the core behavior quickly.

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 3-parameter tool with no output schema, it provides most needed context: what to pass, the verdict rule, defaults, and an edge-behavior warning. However, the exact return shape is not described beyond 'promote/hold verdict,' and the term 'hold-hint' remains slightly under-specified without a schema or further explanation.

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 already documents all three parameters, and the description enriches that by adding default values and the exact condition under which a promote verdict is decided. It does not expand each parameter individually, but with full schema coverage the additional semantics are enough to invoke the tool correctly.

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 identifies the resource (.faf content), what the tool does (scores it, estimates tokens, and returns a promote/hold verdict), and where it sits in the pipeline (pre-promotion quality gate before a Grok Collection). The combined scoring-and-gating role differentiates it from siblings like faf_score and faf_estimate_tokens, even without naming them explicitly.

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 gives a clear usage context and trigger: invoke this before content goes to a Grok Collection, with promotion contingent on both thresholds. It does not explicitly name alternatives to use instead when only scoring or only token estimation is needed, so it lacks explicit exclusions but the context is clear.

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