company_review_outcomes

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

With no annotations present, the description carries the full burden of behavioral disclosure. It does disclose meaningful behavior: the default selection of the two latest persisted reviews, the ability to override via payload refs, and the full scope of computed scoring dimensions. However, it does not state whether this is a pure read/compute operation or whether it has side effects, nor what happens when fewer than two reviews exist. These are notable gaps for a tool with zero annotation coverage.

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 a single run-on sentence packed with comma-separated clauses, front-loading the main purpose before the result list and payload note. It contains no filler, but the dense wall-of-text structure makes it hard to parse quickly. The payload hint is buried at the end rather than structured as a distinct sentence. Compact but poorly organized.

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?

An output schema exists, so the description doesn't need to explain return values. The description covers the observable semantics well: the comparison baseline, the scoring dimensions, and the payload override mechanism. However, for a tool with 7 parameters and zero schema descriptions, the unexplained required bundle_json and project_id parameters leave an agent uncertain how to construct a valid call. The core scoring logic is complete, but the invocation mechanics are not.

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 description coverage is 0%, so the description must compensate for the undocumented parameters. It partially does: it explains the payload_json contents (previous, current, previous_ref, current_ref). But the two required parameters, project_id and bundle_json, are completely unexplained — bundle_json is especially opaque, as its name gives no hint of its role. engine, operation, now, and entity_ref are likewise ignored. The description only covers roughly half the parameters and leaves the mandatory ones the most mysterious.

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 states a specific verb ('Score what happened to the previous intelligence review's actions by the current one') and a clear resource (previous review actions vs. current review). It enumerates the computed outputs (carried/cleared actions, money at stake, roll-up per source document, clearance rate, money released, newly raised actions), which distinguishes it from sibling list tools like company_reviews and company_review_decisions. The dense, jargon-heavy phrasing ('carried or cleared', 'money at stake then and now') slightly obscures the meaning, but the core function is identifiable.

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 implies usage context by stating the default behavior ('by default the two latest persisted reviews') and offering overrides ('optional previous, current, previous_ref, current_ref'). However, it never names alternatives or states when NOT to use this tool versus the many sibling tools (company_reviews, company_review_decisions, company_intelligence_review). The when-to-use guidance is implied rather than explicit.

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