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

Annotations declare a non-destructive write that is not open-world; the description usefully adds that the record persists locally on this machine, that status defaults to "applied", and that an id comes back. It does not say what happens on duplicates or invalid deadlines, which would round out behavior for a write tool.

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-loaded with what the tool does and its default behavior, followed by inputs and a concrete example. The input enumeration is somewhat redundant against the schema but stays a single efficient paragraph; the example prompt earns its space by showing combined usage.

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 annotations, full schema coverage, and an output schema, the description covers everything an agent needs to call this correctly, including the id return value that downstream tools depend on. Missing only edge-case behavior (duplicate entries, deadline format validation) for a fully complete picture.

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 all seven parameters and both enums are already documented in structured form. The description mostly restates that content (required company/role, YYYY-MM-DD deadline, source examples) rather than adding semantics the schema lacks, so baseline 3 applies.

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 verb and resource ("Add a job or internship to the tracker") and immediately clarifies default placement in the applied stage. It also names a downstream consumer ("returns its id, which update_status needs"), which distinguishes it from the sibling tools that read or change existing entries.

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 sequencing hint (the returned id is required by update_status) tells the agent where this fits relative to alternatives, and the worked example prompt anchors realistic usage. It stops short of explicit "do not use this for X" exclusions, but the create-vs-update boundary is implied clearly enough.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing that the report is returned as text with nothing written to disk, and that CSV cells starting with =, +, - or @ get a leading apostrophe to prevent spreadsheet formula execution. These are non-obvious behavioral traits an agent could not infer from structured fields.

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 formats before the CSV-escaping note and example prompt, and every sentence carries information. The example prompt is slightly redundant with the opening sentence, keeping it just below maximum efficiency.

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 an output schema present, the description needn't explain return structure, and it already covers output medium (text), side effects (none on disk), filtering, and format default. Nothing an agent needs in order to call this correctly is missing.

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 100% and both parameters are enums with defaults already documented, so the schema does the heavy lifting. The description restates the default markdown format and the status stage filter without adding syntax or edge-case meaning beyond it, making 3 the correct baseline.

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?

Names a specific verb+resource ("Export your applications") and states the two output formats, so the tool's identity is unambiguous. The line "returned as text and nothing is written to disk" further separates it from the mutation-oriented siblings add_application and update_status.

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 a clear use case ("so you can share them or open them in a spreadsheet") and an example prompt ("Export all my applications as a CSV") that anchors invocation. It does not explicitly state when to prefer a sibling tool or when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real domain behavior: which application stages contribute deadlines versus interviews, that rejected applications and offers are omitted, and that results are date-sorted with reminders. It doesn't discuss volume, but with annotations and an output schema that is acceptable.

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 core purpose and filtering rules are front-loaded, followed by the parameter notes and an example prompt. It is a bit dense in a single block and repeats default values already present in the schema, but no sentence is truly wasted.

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 an output schema available, the description doesn't need to explain return values, and it covers the important remaining context: inclusion rules, sorting, defaults and a sample query. It is essentially complete for a read-only listing 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 coverage is 100%, so the schema already documents all three parameters and their defaults. The description largely restates days and include_overdue, though it does clarify that today means 'ask as if it were another day', which is a small semantic addition beyond the schema. Baseline 3 is appropriate.

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 verb and resource: showing upcoming deadlines and interviews sorted by date, with an explicit reminder per item. It also defines the population precisely (applied-stage deadlines, interview-stage items with interview_date, excluding rejected and offers), which clearly separates it from siblings like add_application, update_status and export_report.

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 inclusion/exclusion rules give a clear sense of when this tool applies, and the example prompt anchors the intended use. It stops short of explicitly naming an alternative (e.g. export_report for a saved file) or stating when not to use it, so 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.

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

Annotations already declare this is a non-read-only, non-destructive mutation. The description adds real behavioral context beyond them: the note is appended to existing notes rather than replacing them, and setting interview status with a date feeds list_upcoming reminders. It doesn't say whether re-setting an existing interview_date overwrites or duplicates it, which keeps it from a 5.

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-loaded with the action and its enum, then parameter guidance, then a concrete example prompt. Every sentence carries information, though the example prompt is slightly redundant with the preceding sentence about interview_date.

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 an output schema present, return values need no explanation. Four params at 100% schema coverage plus description-level detail on formats, provenance, append semantics and downstream effects leave nothing an agent needs missing.

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 the baseline is 3. The description still adds value by documenting id provenance, the accepted date formats, and the append semantics of note, which the schema's terse "A note to add to the application" only hints at.

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 verb and resource ("Move an application to another stage") and enumerates the four valid target stages inline. This clearly distinguishes it from add_application, list_upcoming and export_report, which all serve different functions.

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 explicit conditional guidance ("When the status is interview, pass interview_date so list_upcoming can remind you") and names where the id comes from (add_application or export_report). It stops short of stating when-not-to-use, but for a purpose-specific mutation tool the context is clear.

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