time_to_hire

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

No annotations are supplied, so the description must carry the behavioral burden, and it does state 'Read-only' plus a non-obvious computation rule: the hire date is the accepted offer's resolved date, falling back to the application's last activity. That fallback semantics is exactly the kind of detail an agent cannot infer. It does not mention auth requirements or how created_after interacts with the hire-date window.

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-loads purpose and read-only status, then usage, then the id lookup, then the return shape. Each sentence adds information, though the job_id guidance partially duplicates the schema's own parameter description.

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 return values need not be enumerated, yet the description still lists average/median/min/max and defines the measurement endpoints. Combined with the read-only note and the hire-date resolution rule, an agent has everything needed to call this correctly with or without job_id.

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 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description adds real meaning for job_id (omitting it yields org-wide metrics, and the id comes from list_jobs name matching), but says nothing extra about created_after beyond the schema's ISO 8601 note.

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 metric and scope: 'Time-to-hire metrics for hired candidates' — an agent can distinguish it from sibling analytics tools like pipeline_metrics or source_effectiveness immediately. It also names the population (hired candidates) and the unit (days from application to hire).

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?

Gives concrete triggers ('how long does it take to hire?', 'average days-to-offer') and explicitly routes the two modes — pass job_id for one role, omit for org-wide — including how to obtain the id (list_jobs → match by name). It stops short of naming which sibling metric tools to prefer over this one when the user actually wants funnel or source analysis.

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