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

Goes well beyond the annotations: a backup is taken first, undo_last_write can revert it, the write is refused on a version mismatch, and duplicates are rejected on company+role or link. The annotations only mark it non-read-only and non-destructive; the description supplies the actual safety and failure semantics an agent needs.

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?

Purpose and duplicate rule are front-loaded in the first two sentences, and the confirmation protocol follows in a compact paragraph. Slightly dense, but each sentence carries non-obvious operational 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?

With an output schema present, annotations covering the safety profile, and 100% schema coverage, the description fills the remaining gaps: consent flow, token mechanics, optimistic-concurrency refusal, backup/undo. Nothing needed to call it correctly is absent.

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%, so the schema already documents company, role, link, notes, extra, confirm, dry_run, allow_duplicate and expected_version. The description only reinforces confirm and expected_version, which the schema already explains; it adds no new meaning for the remaining parameters. 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 new row') and pins down the resulting state ('not-applied status') plus the duplicate-refusal rule, which lets an agent distinguish it from edit_application or set_status. It never names a sibling explicitly, so differentiation is inferred rather than declared.

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 concrete usage protocol: write only after user consent, either via the client's own confirmation dialog or via dry_run=true followed by a repeat call with confirm=<token> in a new user message. What is missing is guidance on the create-vs-edit boundary (when to prefer edit_application or allow_duplicate for an intentional second application).

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 only say destructive/non-idempotent; the description adds the real behavioural detail: an undo reverts the column and the config line together, a backup is taken first, the write is refused when expected_version is stale, and the confirm/dry_run handshake is spelled out. That is exactly the context an agent needs before a destructive write.

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 placement, then the confirmation workflow, then safety guarantees — a sensible order. Dense but each sentence carries information; the opening clause about header styling is slightly convoluted but still earns its place.

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 needn't be described, and the description covers the remaining burden for a destructive, non-idempotent mutation: preview flow, confirmation token, version conflict handling, backup, and undo. Nothing an agent needs to invoke it safely 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 coverage is 100%, so the baseline is 3, but the description adds value by explaining why `field` exists (it makes other tools use the column) and by explicitly tying `expected_version` to a refusal on concurrent change. It does not elaborate on `kind`, `options` interaction, or header language, so it sits above baseline but not at 5.

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 column), plus the exact placement and styling rule: inserted after the last column with the header styled like its neighbour's. It also flags the config-mapping side effect for `field`, which no sibling tool does, so the agent can tell it apart from edit_application or fix_tracker.

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?

Explains when to set `field` (so the tools start using the column, checked via describe_tracker's unavailable_tools) and when to omit it, and gives the ordering rationale that columns must be added at the end. It does not name a sibling alternative to use instead when the column already exists, which keeps it short of 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?

Beyond the annotations, the description discloses meaningful behavior: events are all-day, overdue follow-ups are placed on today, each description ends with a tracker-mcp id line, and callers should search the calendar for that id to update rather than duplicate. It also clearly states the tracker is not touched, consistent with readOnlyHint=true. No annotation contradiction is present.

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 compact and front-loads the core concept: open follow-ups rendered as all-day calendar events. Every clause contributes useful information about event format, duplicate avoidance, and tracker isolation, though the semicolon-heavy phrasing is slightly dense.

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?

Given the output schema, annotations, and single fully documented parameter, the description supplies the remaining context an agent needs: it explains the event shape, the embedded tracker-mcp id, duplicate handling, and the fact that the tracker is not modified. No essential behavioral or integration detail appears 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?

The single parameter, days, is already fully described in the schema as 'Follow-ups due up to this many days ahead'. The tool description itself does not add further meaning, constraints, or examples for this parameter. With 100% schema coverage and only one parameter, the baseline score of 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?

The description clearly establishes that this tool exposes open follow-ups as all-day calendar events with date, title, and description, and notes that overdue items appear on today. It is understandable, but it does not explicitly name the closest sibling, export_followups_calendar, or use a direct verb such as 'export' or 'generate', leaving some sibling differentiation implicit.

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 clear usage context: it is for the user's own calendar tool via the sync_calendar prompt, and the tracker is not modified. It also explains how to avoid duplicates by searching the calendar for the embedded tracker-mcp id before adding another event. It does not explicitly compare against alternative tools such as followups_due or export_followups_calendar.

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 openWorldHint=false, so safety is covered. The description still adds real behavioral context: it is per-row diagnostic output, it names the detection heuristics (e.g. dates stored as text, applied column disagreeing with status, reply date recovered from response text), and it flags per-issue fixability. It stops short of describing ordering or whether results are truncated at the limit, which is a minor gap.

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?

It is one long but dense sentence with the core purpose front-loaded ('find what hand edits leave behind, row by row') and the issue catalogue as an efficient list. The nested parentheticals make it slightly heavy to parse, but every clause names a real detection case rather than padding.

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 need not explain return shape, and annotations cover the safety profile; the parameter is documented at 100% coverage. What remains uniquely on the description's shoulders, the set of issues detected and their fixability, is fully spelled out.

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 the single 'limit' parameter is fully documented in the schema (default 200, max 1000), so the baseline is 3. The description adds nothing about what 'limit' truncates or how ordering interacts with it.

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 ('find what hand edits leave behind') on a specific resource (tracker rows) and then enumerates the concrete defect classes it detects, which distinguishes it sharply from siblings like summary, list_applications, and fix_tracker. An agent can tell exactly what this returns without opening the schema.

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 closing line 'Each issue says whether fix_tracker can fix it' establishes the remediation path and implies the check-then-fix workflow. It does not, however, state explicit preconditions or when to prefer describe_tracker or list_applications instead, so the routing is implied rather than spelled out.

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 destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: a backup is taken first, one undo step reverts the whole batch, and the write is refused if expected_version no longer matches. This is exactly the safety and concurrency information an agent needs before invoking a destructive batch mutation.

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?

Content is front-loaded, with the mutation summary first and the confirmation protocol second, and no sentence is filler. The confirmation paragraph is a dense multi-clause sentence, slightly reducing scannability, but the density is justified by the safety-critical content.

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 and rich annotations, the description only needs to cover invocation protocol and risk, both of which it does thoroughly — including the client-dialog vs. token path and the backup/undo guarantee. Nothing required to call this destructive batch tool safely 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%, so the baseline is 3; the description earns extra credit by explaining the sequencing between dry_run and confirm (token obtained from the approved dry run) and the refusal semantics of expected_version. It does not elaborate on formatting of the token or partial-failure behavior across rows, keeping it below a 5.

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 opening states a specific verb and resource ('Close stale applications in one write') and enumerates the exact fields mutated (status, follow-up date, log entry), which separates it cleanly from the sibling stale_applications read tool. An agent can identify the operation without opening the schema.

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 an explicit conditional workflow: if the client provides its own confirmation dialog, proceed; otherwise call with dry_run=true, show the preview, and repeat with confirm=<token> after approval in a new message. It also names undo_last_write as the recovery path and states the rows parameter defaults to the stale_applications set.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: the server writes config on first start and `config_generated` reports where it is and what to check.

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 front-loaded with the tool's purpose and packs useful details into two sentences. It is dense but not wasteful, though the parenthetical and list make it slightly harder to scan.

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 does not need to enumerate return values in full. It still explains the key returned concepts and the first-start config behavior, making it complete enough for a zero-parameter, read-only introspection 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?

The tool takes zero parameters, so parameter semantics are inherently simple and the schema has full coverage. No additional parameter guidance is needed.

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 that this tool reports the tracker's layout: field-to-column mapping, custom fields, headers, statuses, closed statuses, follow-up rule, and unsupported tools. It is specific about the returned information, though it does not explicitly distinguish itself from siblings like check_tracker or fix_tracker.

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?

Usage is implied by references to add_application's `extra` and funnel's `by`, suggesting the tool helps callers learn exact header text before using those tools. However, there is no explicit when-to-use guidance, no exclusions, and no direct comparison with check_tracker or fix_tracker.

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 a destructive, non-idempotent write, and the description adds substantial context beyond them: user confirmation is required, a dry_run/confirm token flow is specified, expected_version guards against concurrent changes, a backup is taken first, and undo_last_write can revert the write. These details are consistent with the annotations and materially improve safe invocation.

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 front-loaded with the purpose and correction examples, then moves into validation, alternatives, and the confirmation workflow. Despite its length, every sentence carries necessary operational detail for a destructive write tool, with no redundant or filler text.

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?

Given the destructive mutation, six parameters, nested fields object, and existing output schema, the description covers everything an agent needs: what can be corrected, which siblings handle related changes, how to preview and confirm writes, how concurrency is guarded, and how undo works. No critical behavioral or procedural gap remains.

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%, so the schema already documents each parameter. The description adds useful semantic detail beyond the schema, particularly date validation rules: a submit or reply date cannot be in the future and a reply cannot precede the submit date. It also clarifies that related status and follow-up changes belong to other tools.

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 states a specific verb and resource: 'Correct fields of one row by hand' with concrete examples such as a wrong date, typo in company or role, furthest stage, link, or custom column. It also distinguishes the tool from siblings by explicitly routing status changes to set_status and follow-up changes to log_followup or reschedule_followup.

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?

It gives clear conditions for use (manual corrections to specific fields) and explicitly names alternatives for related operations: set_status for status, log_followup for sent follow-ups, and reschedule_followup for moved follow-ups. The confirmation workflow further clarifies the required invocation sequence with dry_run and confirm.

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?

Adds real context beyond annotations: the file is written next to the tracker, the tracker itself is untouched, and overdue follow-ups are mapped onto today. Combined with readOnlyHint=false and idempotentHint=true this is coherent, though it doesn't state the filename or whether an existing .ics is overwritten.

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 sentences, front-loaded with the action and artifact, with the alternative pushed to the end. Density is high but nearly every clause carries information; a slight syntax parse cost comes from the embedded parenthetical about overdue items.

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 no explanation, and the description covers side effects and the fallback path. Minor gaps remain around file naming and overwrite behavior for a repeated idempotent export.

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% and the single 'days' parameter is fully documented there, so the baseline applies. The description never mentions the look-ahead window, leaving a reader of the prose alone to wonder how far ahead follow-ups are exported.

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 precise verb and output artifact ('write the open follow-ups as an .ics file next to the tracker') plus the destination use case (Calendar, Outlook, Google Calendar). That clearly distinguishes it from followups_due, which returns the same data as tool output rather than a file.

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 an explicit routing rule: if the client has a calendar tool, add events there instead, since followups_due carries the same data. It does not address the sibling calendar_events or explain when a file export is preferable to reading calendar events, which keeps it short of 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?

Beyond the destructiveHint annotation, the description discloses that the tool takes a backup, performs one write and one undo step, requires the user's yes, and supports undo_last_write. It also explains the version-check refusal behavior, which is important for a destructive 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?

The description is front-loaded with purpose and then safety workflow, and every sentence earns its place. The enumeration of fixes is dense but useful for an agent deciding whether this tool will make the needed changes.

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 destructive multi-fix mutation with an output schema, the description covers the essential context: what gets fixed, the approval protocol, backup and undo behavior, and version-conflict handling. Nothing critical is missing for correct invocation.

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, but the description adds meaningful workflow semantics for dry_run, confirm, and expected_version that the schema alone does not fully convey. It does not add much beyond the schema for rows and kinds, which keeps it from a 5.

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 states a specific verb and resource ('Fix the fixable issues check_tracker found') and enumerates the exact repairs performed. It clearly differentiates this tool from check_tracker, which detects issues, and undo_last_write, which reverses writes.

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?

It gives explicit workflow guidance: use after check_tracker, call with dry_run=true first unless the client shows its own confirmation dialog, then repeat with the confirm token after user approval. It also states that writes are refused if expected_version no longer matches.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: overdue items are included in the window, and applications with no follow-up date at all are appended to the result set — a non-obvious composition rule an agent would otherwise miss.

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?

One dense sentence with no filler, and the primary criteria are front-loaded before the secondary 'no follow-up date' clause. Slightly compressed phrasing ('due by today + within_days') costs a little readability but nothing is 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?

An output schema exists, so return shape needn't be explained, and annotations cover safety. For a single optional-parameter read tool, the description supplies what structured fields cannot: inclusion rules, the today anchor, and the union with undated applications. Only ordering/sort behavior is unstated, which is minor.

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% (single param documented as 'Look this many days ahead' with default 7, range 0-60), so baseline is 3. The description adds the reference point the schema lacks — the window is anchored at today and extends forward, with overdue included — which meaningfully interprets within_days=0 and the default.

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 resource (follow-ups) and precisely states its selection scope: due by today + within_days, overdue included, plus submitted applications lacking a follow-up date. That distinguishes it from mutation siblings like log_followup/reschedule_followup, though the verb is implicit and no sibling is named as an alternative.

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?

Usage is implied by the selection criteria rather than stated: an agent can infer this is the 'what's due' query, but nothing says when to prefer it over stale_applications, summary, or export_followups_calendar. No exclusions or prerequisites are given.

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?

Read-only behavior is already declared by readOnlyHint, so the description wisely spends its words on semantics instead: it clarifies that a rejection counts as a reply and that stages come from the tracker configuration, which an agent could not infer otherwise. It does not mention pagination or performance characteristics, but that is a minor omission for an aggregate read 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?

Two sentences, no filler: the first names the metric and its edge case, the second states the aggregation and rate basis. Front-loaded and every clause carries 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?

With an output schema present, full parameter documentation and read-only annotations, the description need only supply the conceptual model, and it does: what counts as a reply and where stage definitions come from. The only gap is the absence of explicit routing guidance among the many sibling analysis tools.

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%, with 'by', 'since' and 'until' each fully documented including defaults and allowed values. The description only alludes to grouping ('per group') and date scoping ('submitted') without adding anything 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?

The description states a specific computation: conversion of submitted applications into reply counts and configured funnel stages, aggregated in total and per group with percentage rates. It is clear what the tool produces, but it does not explicitly distinguish itself from analytics-focused siblings such as summary or reply_times.

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?

Usage is only implied by the tool's analytical nature; there is no explicit statement of when to use this versus summary or reply_times, nor any exclusions or prerequisites. The 'as configured' phrasing hints that the tracker must be inspected first (describe_tracker) but does not say so as a precondition.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail: it returns every column plus notes and the follow-up log, and a text query matching several rows returns all matches. It does not specify no-match behavior, but otherwise adds solid context beyond annotations.

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 front-loaded with what is returned, then how to locate it, then usage guidance and the sibling alternative. Every sentence contributes useful selection or invocation information without padding.

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?

Given the tool's low complexity, two fully documented parameters, existing output schema, and read-only annotations, the description is complete enough. It covers return scope, lookup modes, multi-match behavior, workflow usage, and the relevant alternative 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 100%, so the schema already documents `row` as an exact sheet row number and `query` as company or role text. The description adds meaningful semantics by explaining that `query` can match multiple rows and return all of them, though it does not clarify precedence if both parameters are supplied.

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 states a specific retrieval resource and scope: 'Everything recorded for one job application: every column, the notes and the follow-up log.' It also distinguishes this tool from the sibling list_applications by noting that list is for browsing many rows in brief.

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?

It explicitly gives a workflow condition: 'Use it before a write to show the user the current values.' It also names the alternative for a different need: 'To browse many rows in brief, use list_applications.'

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 openWorldHint=false, so safety is covered, and an output schema exists. The description still adds real value by disclosing the compact one-line-per-application projection, which is why an agent picks this over get_application. It stops short of mentioning the default 100-row cap or any truncation behavior beyond the limit parameter.

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?

Four short sentences, front-loaded with purpose and output shape, followed by filter affordances and then sibling routing. No filler and nothing buried.

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 a fully documented schema and an output schema covering return values, the remaining burden is scope and routing — both fully handled. Nothing an agent needs 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%, so all six parameters are self-documenting. The description's sentence about filtering by status, company/role text, submit dates, and open-only merely restates those parameters in prose without adding syntax or edge-case guidance. 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 ('Browse the job applications in the tracker') and immediately defines the shape of what comes back ('one line each: row, company, role, status, submit and follow-up dates'). This makes it clearly distinguishable from get_application, which returns every column of a single row.

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?

Explicitly routes to alternatives by task: 'For every column of one row use get_application. For counts use summary or funnel, and for what is due use followups_due.' It also lists the filter dimensions inline, so the agent knows which narrowing options exist before opening the schema.

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?

The description goes well beyond the annotations by explaining the consent requirement, the dry_run/confirm-token flow, the expected_version conflict check, and the backup/undo behavior. These details are important for a destructive, non-idempotent write tool and are not contradicted by the annotations.

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 dense but well structured and front-loaded: it states the core action first, then alternatives, then the write-safety workflow. Given the tool's complexity and confirmation requirements, every sentence carries useful 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?

Although an output schema exists, the description provides the behavioral context an agent needs: when to use it, what it mutates, how confirmation works, conflict handling, and rollback. It is complete for a complex write tool with eight parameters.

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%, so the baseline is 3, but the description adds useful semantics beyond the schema: final=true clears the date and prevents further follow-ups, next_on defaults from the follow-up rule, and confirm is tied to the dry-run flow. It does not individually explain every parameter, but it substantially enriches the important interactions.

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 states a specific verb and resource: recording a follow-up the user actually sent for one job application. It also distinguishes the tool from reschedule_followup, set_status, and followups_due, so an agent can select it without opening sibling schemas.

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?

It explicitly says when to use this tool versus alternatives: use reschedule_followup when nothing was sent, set_status when the company replied or the application closes, and followups_due to list what is due. The confirmation workflow for writes is also clearly described.

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 annotations: it enumerates the exact fields mutated (applied flag, submit date, channel, status, follow-up date, follow-up log line), the situations that are refused (already applied, tracker changed since expected_version), the duplicate-company warning, and that a backup is taken and undo_last_write reverts. This is what makes a destructiveHint=true write safe to invoke.

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 core action and alternatives, then the confirmation workflow, then conflict/backup guarantees. Dense but nearly every sentence carries distinct information; the phrasing is a little long-winded in the multi-clause status sentence but nothing is redundant.

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 and 100% parameter coverage, the description need only cover side effects and workflow, which it does fully: confirmation token flow, version conflict behavior, backup/undo, and cross-tool routing. Nothing an agent needs 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 coverage is 100%, so baseline is 3, but the description adds real semantics: followup_on overrides the follow-up rule while an existing date is otherwise kept, and confirm/dry_run are explained as a paired workflow rather than isolated fields. It does not restate row/applied_on, which the schema already covers well.

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 precise verb+resource: records that an application already present as a row was submitted, and names the sibling (add_application) that handles the not-yet-tracked case. An agent can distinguish this from add_application, edit_application and set_status without opening any schema.

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?

Explicit routing: 'Add a new one with add_application first', 'correct its date with edit_application', 'Replies and closing go through set_status'. It also states the precondition (row must already exist) and the two-step confirmation procedure, so both when to use and when not to use are covered.

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 openWorldHint=false. The description adds real value beyond that: it states the output is advisory, that each message is paired with the write tool that would record it, and that sender/company attribution comes from subject, sender name or domain rather than ATS vendors. It omits the 200-message cap and any failure behavior, keeping it below 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?

Content is front-loaded with the meaning of the output, then the attribution rule, then the workflow caveat. A couple of clauses run long (the ATS parenthetical, the final sentence), but every sentence carries 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?

Output schema exists, yet the description still tells the agent what the rows and write-tool pairing mean, which is the non-obvious part. Combined with the single fully-documented parameter and clean annotations, nothing needed to call it 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%, with the messages parameter fully documented ({from, subject, date, snippet}, ISO/RFC 2822 dates). The description restates that these are e-mails from the user's mailbox but adds no new syntax or constraints, 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?

Names a specific verb (match) and resource (e-mails to applications), then enumerates the output categories (confirmation, rejection, interview, offer). The agent can tell exactly what it gets back without opening the schema.

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?

Explicit procedural guidance: fetch messages with the mail tool first, apply changes with the write tool only after the user's yes, and treat results as suggestions. It doesn't name a sibling alternative (e.g., list_applications) for the non-email case, so it stops short of full when-not 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 openWorldHint=false, so the safety profile is settled; the description still adds real value by disclosing ordering, per-entry payload, the fact that entries correspond to what undo_last_write reverts, and the omission of external/manual edits. It stops short of covering limit/truncation behavior when more writes exist than the requested count.

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?

Four short sentences, front-loaded with the core identity, then contents, then usage, then the scope caveat. No redundancy with the title or schema; every sentence adds new 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?

For a simple, annotation-covered read tool with an output schema and a fully described single parameter, the description supplies everything an agent needs: what it returns, ordering, how to use it, and its blind spot. Nothing material 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?

The single limit parameter is already fully documented in the schema (min 1, max 200, default 10), so the schema carries the semantics. The description says "newest first" but never mentions how the limit interacts with ordering or what happens when the limit truncates history — 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 — an audit log of this server's writes to the tracker — plus ordering (newest first) and per-entry contents (time, tool, row, backup file, changed cells with old/new values). This clearly separates it from generic read siblings like get_application or summary.

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 use cases ("answer 'what did you change?' or to check that a write landed"), names the related tool it feeds (undo_last_write would revert these entries), and states an exclusion: manual edits in Excel or Sheets are not captured. When-to-use, relationship, and scope boundary are all covered.

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 openWorldHint=false, so safety is covered; the description adds genuinely new context: the tool depends on reply-date data, results degrade without it, and the silence table is a conditional 'of those silent at day N, how many later heard back' construct rather than raw counts. It stops short of saying what happens when there are zero replies or too few data points, which is the one gap.

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 core metric before the silence-table explanation, and every clause carries information — no filler. The middle sentence is long and stacks two outputs plus a threshold list, which slightly hurts scannability.

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 no explanation, and the description still pre-explains the non-obvious silence-table semantics and the data dependency. For a read-only, zero-required-param analytics tool, nothing an agent needs in order to call it 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 params (`by`, `since`) carry their own descriptions, including a cross-reference to funnel for `by`. The prose adds no format, enum, or value examples beyond the schema, 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+resource with real precision: median and 75th-percentile days from submission to first reply, plus a silence table with explicit day thresholds. This is clearly distinguishable from siblings like funnel, summary, and stale_applications, which an agent could otherwise confuse with it.

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?

Explicitly says 'Use it to decide when to close silent applications,' which ties the tool to a concrete decision and implicitly routes the agent away from stale_applications/summary. It also names the prerequisite (reply dates, filled by set_status or backfilled by check_tracker). It does not explicitly exclude or compare against the closest alternative, close_stale, so it falls short of 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?

Goes well beyond the annotations: it documents the confirmation protocol (client dialog or dry_run plus confirm token), the expected_version conflict refusal, the automatic backup, and that undo_last_write reverts the change. This is strong disclosure for a destructiveHint=true write. Minor gap: it doesn't say what the dry_run preview or confirmation dialog actually contains.

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?

Purpose and alternative routing are front-loaded in the first two sentences, with the write-safety protocol following. Dense but nearly every sentence carries distinct information; the second paragraph is slightly run-on and could be split for scanability.

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 destructive, six-parameter write tool with an output schema available, the description covers the full decision surface: when to call, what not to call, the confirm/dry_run flow, concurrency refusal, backup, and revert path. Nothing needed to invoke it 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 coverage is 100%, so baseline is 3; the description still adds workflow meaning to confirm and dry_run by explaining the preview-then-repeat-with-token sequence that the per-parameter text only states statically. It adds no detail beyond the schema for row, on, reason, or expected_version.

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 the next follow-up to another date, or plan none') and immediately constrains it with a condition ('when nothing was sent'), with concrete examples. It is clearly separable from log_followup (a follow-up was sent) and set_status (close an application), both named explicitly.

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 when-to-use conditions (no one to write to yet, waiting for message credits, company promised an answer by a date) plus when-not-to with two named alternatives and their triggering conditions. Nothing about sibling selection is left to inference.

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?

Despite annotations covering safety profile (destructive, non-idempotent), the description adds substantial context: dropdown constraint, describe_tracker reference, date-appending behavior, furthest-stage monotonicity, reply-date and follow-up clearing semantics, plus a full confirm/dry_run/expected_version workflow with backup and undo. This is far beyond what annotations alone convey.

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?

Purpose and sibling routing are front-loaded, then the confirmation workflow. Dense but every sentence carries operational info; a bit long but well organized.

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 explained. For an 8-param mutating tool, the description fully covers when to use, alternatives, behavioral side effects, and the confirmation/versioning protocol an agent needs to call correctly.

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%, baseline 3. The description adds meaningful semantics on top: status must come from the tracker dropdown listed by describe_tracker, `on` feeds the reply date only on first reply, response/note are appended, and the confirm/expected_version flow is explained operationally.

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+resource+scope: 'Change the status of one job application'. It is explicitly distinguished from mark_applied, close_stale, and edit_application, so an agent can route to it without opening schemas.

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 clear when-to-use ('when the company replies or the application ends') plus explicit alternatives: mark_applied for new submissions, close_stale for many silent applications, edit_application for other cells.

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 openWorldHint=false, so the safety profile is covered; the description goes further and defines the non-obvious computation: 'last touch' is the submit date or the newest *dated* follow-up log entry, explicitly excluding moved and dropped follow-ups. That is exactly the kind of internal rule an agent could not infer and would otherwise get wrong.

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 sentences, zero filler: the definition comes first, the sibling relationship last. Every clause (silence window, last-touch definition, follow-up exclusion) carries distinct semantic load rather than restating the name or title.

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, and the single optional parameter is fully documented. The one behavioural subtlety that could cause a wrong call – what counts as the last touch – is spelled out, so nothing an agent needs 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 coverage is 100% ('Silent at least this many days', default 30), so the baseline is 3. The description adds real meaning by specifying the reference point the day count is measured from (submit date or newest dated follow-up, ignoring moved/dropped ones), which the schema field alone does not state.

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 resource (applications awaiting a reply) and gives the exact membership criteria: a waiting status, silence of `days`+ days, and no follow-up scheduled today or later. It explicitly distinguishes the set from related siblings in both directions – these are NOT followups_due (no future follow-up) and these are exactly what close_stale closes – so an agent can pick it apart from the 22 siblings without opening a schema.

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 criteria themselves imply when to call it (auditing neglected applications), and the closing clause routes the agent to `close_stale` as the write counterpart of this read. There is no explicit 'use this instead of X when Y' exclusion or prerequisite statement, so it stops short of a 5, but the context is clear rather than merely implied.

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?

The annotations already declare this is a read-only, closed-world tool. The description adds the important cohort nuance: since/until filters by submission period while statuses reflect where applications stand now. It does not specify boundary inclusivity or empty-range behavior, so it is strong but not exhaustive.

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 definition is front-loaded with the core behavior, then explains parameter effects, then routes to alternatives. Every sentence earns its place, and the size is appropriate for a two-parameter summary tool.

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?

The tool is a read-only summary with two optional parameters and an output schema. The description covers purpose, parameter behavior, and sibling alternatives, leaving no material gap for correct invocation.

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%, and the schema itself documents since/until as period bounds for the submitted cohort. The description adds useful meaning beyond the schema by explaining that the result shows applications submitted in that period and their current status, though it does not add date-format or inclusivity details.

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 states a specific verb and resource: it counts job applications in the tracker. It names the concrete breakdowns (status, submitted/not-yet, submissions per month) and distinguishes itself from funnel and reply_times.

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?

It explicitly routes overlapping analytical questions to alternatives: funnel for reply/interview rates, reply_times for reply speed, and followups_due/stale_applications for next actions. It also clarifies the added behavior when since/until are supplied.

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 flag destructive/non-idempotent, but the description adds real behavior: the write is refused if the file changed since the last write, refusal also occurs if the tracker moved past expected_version, and the confirm token must come from a user-approved dry run. These are workflow-critical traits no annotation conveys.

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?

Purpose is front-loaded and every sentence carries operational content. Minor redundancy: the closing line about the tracker changing since expected_version restates the earlier file-changed refusal, and 'the write is refused' appears twice.

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 and annotations covering the safety profile, the description needn't explain return values; it instead covers the confirmation protocol, refusal conditions, and version guard — everything an agent needs to call this destructive undo safely.

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, but the description goes further by tying confirm, dry_run, and expected_version into a concrete approval workflow rather than restating field meanings. It stops short of naming token lifetime or reuse rules.

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 first sentence states a specific verb and resource with scope: 'Restore the file to its state before this server's last write.' That is unambiguously distinct from sibling listing tools like recent_writes or describe_tracker, and an agent can pick it without opening the schema.

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?

It spells out two mutually exclusive invocation paths — client-side confirmation dialog, or dry_run=true then repeat with confirm=<token> after the user agrees in a new message — and states the precondition (expected_version) that causes refusal. When-to-use and when-not are both explicit.

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