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

The description adds substantial behavioral detail beyond the read-only, idempotent, and non-destructive annotations: the report is flat, excludes candidate/draft/recipient/kit/provider data, and delivery_unknown is never delivered and never retried. It also discloses that results are mode-scoped, which is not present in the annotations.

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 dense but efficient: each sentence adds information about output shape, per-mode contents, exclusions, delivery_unknown semantics, filtering, and mode scope. There is no redundancy with the title or annotations.

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 read-only list with two optional parameters, the description covers what is returned and how to filter by built-in-agent id. The main gaps are the undocumented request_id parameter and the absence of any output field or pagination detail, but the essential invocation context is present.

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 description explicitly maps built_in_agent_id to filtering, but it never explains request_id, its purpose, or whether it is required. Since the schema provides no parameter descriptions and the description covers only one of two parameters, the agent is left with incomplete guidance for invoking the tool.

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 opens with a specific verb and resource: 'List the organization's built-in-agent run history' and clarifies the result is a flat work report. It also identifies the two built-in-agent modes covered, which distinguishes this tool from sibling list tools like yardstick_built_in_agents_list and yardstick_automation_runs_list.

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 gives useful context for when this tool is relevant, such as nightly screening reports and interview-kit preparation. However, it never names alternative tools or states when not to use this tool, so an agent must infer routing from sibling tool names rather than being told.

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