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

Annotations already cover read-only/non-destructive, but the description adds non-obvious operational context: workspace_id and user_id are injected from request headers rather than passed as arguments, and actor_id is an internal field that must not be surfaced to users. The 'Behavior: read_only' line merely restates the annotation, but the injection and redaction notes are genuine value-adds.

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?

Front-loaded with the core purpose and reasonably tight, but it wastes a line on 'Behavior: read_only' which duplicates the annotation, and the closing sentence labels reason/declined_reason/acted_on_behalf_of_referrer/new_holder_id as 'pagination info', which is misleading framing for return fields already covered by the output schema.

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 need not enumerate return values, and it correctly focuses on preconditions, implicit header-derived parameters, and the internal-field redaction rule. What is missing is only differential guidance against the sibling state/transition tools, which is a modest gap for a straightforward single-record read.

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 0% with no descriptions on either parameter, so the description has to carry the load and largely does: referrer_id is defined as the workspace member holding the SUPER_CONNECTOR role and referrer_request_id is identified as a UUID. Type/format detail beyond 'UUID' and any error behavior for unknown IDs are absent.

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?

States a specific verb and resource: fetch a single referrer request by UUID scoped to a given referrer, with a short list of what the payload contains (state, decline reason, reason text, timestamps). It is clear what the tool does, though it never explicitly contrasts itself with the closely-named siblings referrer_request_get_current_state or referrer_request_get_state_machine_transitions.

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 'Use when' sentence gives concrete preconditions (you hold referrer_request_id and referrer_id) and a motivating scenario (need status/decline reason/timestamps before SendStateChangeEvent). It lacks a when-not-to-use clause or a pointer to the narrower state-only siblings, so the boundary against alternatives remains implicit.

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