tracker_add

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

The annotations indicate this is a non-read-only, non-destructive mutation, but the description adds crucial behavioral details: repeated saves return the existing tracked job, and previously removed jobs are restored with their earlier status and notes. This goes beyond the structured metadata and provides clear behavioral transparency.

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 well-structured with a purpose statement, alternative guidance, and field details. However, it repeats the full sub_status enumeration that is already in the schema, which adds unnecessary length. The front-loaded purpose and behavior summary are concise, but the field list could have referenced the schema instead of duplicating it.

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 tool with four parameters and an output schema, the description covers purpose, alternatives, parameter semantics, default behavior, return value, idempotency, and restoration. It is complete enough for an agent to correctly invoke the tool without ambiguity or missing context.

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 schema already provides 100% description coverage for all parameters, so the baseline is 3. The description adds valuable context by noting job_id is required, specifying the default for status ("saved"), and clarifying the source of job_id (from jobs_search results). These additions enhance understanding beyond the schema.

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 clearly states the tool tracks a job from jobs_search results using its job_id, which is a specific verb+resource+identifier. It explicitly distinguishes itself from tracker_add_external, which is for jobs found elsewhere on the open web. This provides strong differentiation from sibling tools.

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 explicit when-to-use guidance: use this tool for jobs from jobs_search, and tracker_add_external for jobs with a URL but no jobs_search job_id. It also describes behavior on repeated saves and restoration of removed jobs, which informs usage expectations.

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