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

The description asserts a dry-run behavior with 'Preview', 'no records written' in the title, and 'no application conversion side effects.' This directly contradicts the annotation readOnlyHint: false, which signals the tool may not be read-only. Because the description conflicts with the provided annotation, the score must be 1 per the rubric. The extra detail about JSON-only input and low-confidence match handling would otherwise be valuable behavioral disclosure, but the contradiction undermines trust.

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 dense sentence with no filler. It front-loads the primary purpose and packs the key constraints (JSON only, no raw file reads, no conversion side effects, explicit apply decisions for low-confidence matches). A more structured layout could improve scannability, but the content is tight and every clause adds information.

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 tool with 9 parameters, nested arrays, and no output schema. The description does not explain what the preview returns (e.g., validation errors, match summaries, or confirmation), nor does it clarify which parameters are typically required despite none being marked required. It also gives no usage examples or guidance on constructing the import payload. The description is incomplete for safe and correct invocation of such a multifaceted dry-run import tool.

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% and there are 9 parameters, so the description must compensate. It only mentions 'source_kind: csv' and 'JSON rows only,' giving a hint about source_kind and input format, but it does not explain the meaning or relationships of jobs, candidates, applications, metadata, request_id, session_id, source_label, or idempotency_key. The description names the main resource categories but leaves most parameter semantics to the schema, which is insufficient at this parameter count and coverage level.

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: 'Preview a structured-row ATS import of candidates, jobs, and applications.' It clearly scopes the tool to CSV-style structured rows and distinguishes it from related apply/read tools by emphasizing 'preview', 'dry run' in the name, and 'no application conversion side effects.' An agent can tell this apart from yardstick_ats_imports_apply and yardstick_ats_imports_read without deeper inspection.

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 provides clear context for when to use this tool: before applying an import, with JSON rows only, and when avoiding side effects or raw CSV/archive reads. It does not explicitly name the alternative apply tool or state 'use this instead of apply when you only want validation,' but the constraints strongly imply a dry-run workflow. The absence of explicit 'when not to use' wording keeps this at a 4 rather than a 5.

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