Tailoring Score Lift

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so safety is covered. What the description adds is genuinely beyond that: the return shape is grouped per role category with an additional overall row. It still leaves the unit of 'lift' (raw points vs. percentage) and empty-result behavior unstated, so it is good but not complete.

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?

Two tight sentences with the core definition front-loaded and the filter caveat last; no filler. The shorthand 'role/level/type' is slightly compressed relative to the schema's actual field names, which costs a little clarity but not economy.

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?

With no output schema and 0% schema description coverage, the description must carry the burden and does cover purpose, aggregation grouping, and the optional-filter behavior. It omits valid filter values, the scale/unit of the lift score, and how many rows to expect, which an agent needs to interpret or call this confidently.

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% for three nullable string parameters. The description maps loosely onto them ('role/level/type' covering role_category, level, employment_type) and confirms they are optional filters, but gives no accepted values, matching semantics, or whether filters are exact or partial. It compensates only partially.

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 names a specific computed metric (tailoring lift on match score, base->tailored) and its aggregation unit (per role category plus an overall row), which distinguishes it from sibling explore_* tools like explore_fit_distribution or explore_ats_over_time. It does not explicitly name an alternative sibling, but the resource being measured is unambiguous.

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 only usage cue is that filters are optional. There is no statement of when to reach for this tool versus explore_fit_distribution, score_ats, compare_ats, or get_tailoring_session, nor any prerequisite or scope condition. The agent must infer intent from the metric name alone.

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