company_contribution_bridge

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

With no annotations, the description carries the burden of behavioral disclosure. It does communicate meaningful computational behavior: the results must sum exactly to the contribution change and include the largest driver. However, it does not state whether the bridge is persisted/written, what side effects occur, what authentication is needed, or whether the operation is reversible. No contradiction with annotations exists because none are provided.

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 contains no filler, and the verb/resource are front-loaded. However, it is a single dense run-on sentence with a trailing parenthetical for the payload, making it harder to parse than necessary. The large list of effect types and the invariant are crammed into one clause rather than broken into more readable structure.

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?

This is a complex build-style operation with no annotations, 7 undocumented parameters, and no side-effect disclosure. The description explains the computation and window payload but omits how to populate required fields like project_id and bundle_json, whether the bridge is a persisted artifact or a computed response, and any usage preconditions. The output schema helps with return shape, but invocation details remain incomplete.

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 has 0% description coverage across 7 parameters, so the description must compensate. It only adds meaning for payload_json by naming previous_window_start, window_start, and optional window_end. The required parameters project_id and bundle_json, plus now, engine, operation, and entity_ref, remain unspecified, leaving an agent unable to confidently construct a valid call.

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 action ('Build') and resource ('sealed contribution bridge between two windows'), and details exactly what it computes: per-SKU effects for volume, mix, price, fee, COGS, fulfilment, and return handling, summing exactly to the contribution change, with the largest driver named. This distinguishes it from generic analytics siblings like company_unit_economics or company_product_margin, although jargon like 'sealed' and 'persisted commerce chains' is unexplained.

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 clearly implies when to use this tool: to decompose and explain contribution changes between two windows, with window identifiers supplied via payload (previous_window_start, window_start, optional window_end). It does not mention sibling alternatives or exclusion conditions, but the context is clear enough for an agent to select it for this kind of bridge analysis.

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