Skip to content

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

fix(mcp): align tool annotations with actual behavior

Amruth Pillai2c7f4176356f
diff --git a/.agents/docs/mcp-tool-annotations.md b/.agents/docs/mcp-tool-annotations.md
new file mode 100644
index 000000000..80edc50ca
--- /dev/null
+++ b/.agents/docs/mcp-tool-annotations.md
@@ -0,0 +1,179 @@
+# MCP tool annotation review
+
+Audit date: 2026-10-24. This is the reviewer justification for every registered tool, including API aliases and browser handoffs. Annotations describe the tool call itself and every supported input branch, including indirect cleanup and scheduled effects. The server uses the same metadata for SDK registration, `tools/list` and the public server card.
+
+All four hints are explicitly `true` or `false`; none is omitted or `null`. Adding an API tool requires a classification in `PARITY_ANNOTATIONS`. Regression tests check the complete inventory, these documented values, and SDK/server-card agreement.
+
+## Meaning of each hint
+
+Definitions follow the [MCP ToolAnnotations specification](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations).
+
+- `readOnlyHint`: `true` means the operation reads/returns data without changing account state; `false` covers any supported branch that writes, deletes, cleans up or schedules work. Incidental caching, rate-limit accounting and request logging are not document mutations.
+- `destructiveHint`: `true` covers replacement/removal of existing data or state, including reversible updates and Trash. `false` means no mutation or only additive changes. It is explicitly false for read-only tools even though MCP only interprets it for writes.
+- `idempotentHint`: `true` means repeated identical calls have no additional environmental effect. It does not promise identical response bytes: live reads and signed URLs can change. `false` avoids promising safe retries for new records, revisions/history, fresh timestamps, notifications, external provider requests or time-dependent cleanup. It remains explicit for read-only tools even though MCP only interprets it for writes.
+- `openWorldHint`: `true` means the tool can interact with external AI/search/public pages, public viewers/files, or schedule future external work. `false` means interaction stays within Reactive Resume and its account-owned database/storage/stream infrastructure. Merely returning a URL does not fetch it or execute the later browser workflow. Reading a saved URL or configuring an internal provider reference is not a call to that service.
+
+In the tables, **R**, **D**, **I**, **O** mean `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Each row explains the writes, retry effects and interaction boundary that justify its four values. For closed-world writes with I=false, no general retry guarantee is advertised; updates may touch timestamps, revisions, linked data or notifications, or fail on stale state.
+
+## Behavior evidence
+
+- Primary tools: `packages/mcp/src/tools.ts`, `packages/mcp/src/tool-meta.ts` and the resume, cover-letter and application services/AI handlers in `packages/api/src/features/`.
+- API aliases: `packages/mcp/src/parity.ts` (including the export-URL interception), the allowlisted handlers in `packages/api/src/features/`, and `packages/api/src/routers/rest.ts`.
+- Important conditional effects: `documents/service.ts` (`list` calls `purgeExpired` for Trash; `copyForJob` can replace the working resume); `ai-providers/service.ts` (`list` can synchronize a managed record; `test` replaces status); `agent/service.ts` and `agent/streams.ts` (send persists/generates, resume only reconnects); `career/service.ts` and `career/jobs.ts` (tracking is deduplicated under a lock; schedules can cause later external work).
+- All tools: `packages/mcp/src/annotations.ts` defines complete boolean profiles; `tool-annotations.test.ts` checks inventory and this review table; `parity.test.ts` checks wire discovery against the server card.
+
+## Primary tools
+
+| Tool | R | D | I | O | Behavior justification |
+| ----------------------------------- | ----- | ----- | ----- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_resumes` | true | false | true | false | Reads owned resume records without changing them or contacting external services. |
+| `list_resume_tags` | true | false | true | false | Reads account resume tags without writes or external calls. |
+| `read_resume` | true | false | true | false | Reads owned resume data and metadata without writes or external calls. |
+| `download_resume_pdf` | true | false | true | false | Checks ownership and creates a time-limited signed URL without rendering, uploading or changing the resume. A different token on repeat is not an additional environmental effect. |
+| `create_resume` | false | false | false | false | Creates a private account resume; repeats can add resumes; no external publication or provider call. |
+| `import_resume` | false | false | false | false | Creates a private resume from supplied JSON; repeats add records; no remote import source or AI call. |
+| `duplicate_resume` | false | false | false | false | Creates a separate private resume; repeats add copies without replacing the original or publishing them. |
+| `apply_resume_patch` | false | true | false | true | Can remove/replace existing resume content and writes edit history; a public resume changes for external viewers; repeats may append items/history or conflict. |
+| `update_resume` | false | true | false | true | Replaces resume content/metadata and writes history; can publish or change a public share link. |
+| `delete_resume` | false | true | false | true | Moves a resume to Trash, disabling its public share link and updating Trash state. |
+| `lock_resume` | false | true | false | false | Replaces the lock state and emits a document update on every call; stays within the account. |
+| `unlock_resume` | false | true | false | false | Replaces the lock state and emits a document update on every call; stays within the account. |
+| `get_resume_statistics` | true | false | true | false | Reads owned view/download counters without incrementing them or contacting external services. |
+| `list_cover_letters` | true | false | true | false | Reads the private letter library without writes or external calls. |
+| `read_cover_letter` | true | false | true | false | Reads an owned letter without writes or external calls. |
+| `create_cover_letter` | false | false | false | false | Creates an owned letter and optionally fills an empty application link; does not replace an existing letter link; repeats can add letters; no external calls. |
+| `update_cover_letter` | false | true | false | false | Replaces owned letter fields/links, increments revision and writes history; stale repeated writes can conflict; no public publication or provider call. |
+| `refresh_cover_letter_style` | false | true | false | false | Replaces owned letter styling/source link and increments revision; stale repeats can conflict; no external calls. |
+| `duplicate_cover_letter` | false | false | false | false | Creates a separate private letter; repeats add copies without replacing the original. |
+| `delete_cover_letter` | false | true | false | false | Moves a private letter to Trash and increments its revision; stale repeats can conflict; no public link or external call. |
+| `export_cover_letter` | true | false | true | false | Returns owned letter JSON without saving, publishing or contacting another service. |
+| `import_cover_letter` | false | false | false | false | Creates a private letter from supplied JSON; repeats add letters; no remote source or provider call. |
+| `list_applications` | true | false | true | false | Reads account applications without writes, employer contact or external requests. |
+| `read_application` | true | false | true | false | Reads an owned application without writes or external requests. |
+| `list_application_tags` | true | false | true | false | Reads account application tags without writes or external requests. |
+| `get_application_stats` | true | false | true | false | Reads account application totals without writes or external requests. |
+| `create_application` | false | false | false | false | Creates an account application/timeline entry; repeats add applications; does not submit to an employer. |
+| `update_application` | false | true | false | false | Replaces owned application fields and can append timeline/history or delete replaced owned attachments; no employer contact or public publication. |
+| `add_application_note` | false | false | false | false | Appends an account timeline note; repeats add notes; no external calls. |
+| `add_application_interview` | false | false | false | false | Appends an account interview entry; repeats add interviews; does not send calendar invitations. |
+| `update_application_interview` | false | true | false | false | Replaces owned interview fields and may adjust internal preparation schedules; no invitations or external calls. |
+| `update_application_timeline_entry` | false | true | false | false | Replaces an account timeline entry; no employer contact or external calls. |
+| `delete_application_timeline_entry` | false | true | false | false | Deletes an account timeline entry and associated internal coaching/schedule data where applicable. |
+| `delete_application` | false | true | false | false | Deletes an owned application and associated private account data/files; does not contact employers or remove a public resume. |
+| `bulk_update_applications` | false | true | false | false | Replaces fields across owned applications and can append activity or remove replaced private attachments; no employer contact. |
+| `bulk_delete_applications` | false | true | false | false | Deletes owned applications and associated private account data/files; does not contact employers or delete public resumes. |
+| `import_applications` | false | false | false | false | Adds applications from supplied records; repeats add records; no remote source or employer submission. |
+| `attach_application_document` | false | true | false | false | Replaces a private PDF attachment and deletes its unreferenced owned file; repeats can upload another file; does not send documents to employers. |
+| `remove_application_document` | false | true | false | false | Clears a private attachment and deletes its unreferenced owned file; does not affect publicly shared resumes or call employers. |
+| `autofill_application_from_job` | false | true | false | true | Calls configured AI with supplied posting text; returns fields without saving an application; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `score_application_match` | false | true | false | true | Sends resume/posting context to configured AI and replaces saved match score/metadata; repeats call AI again. |
+| `tailor_resume_for_application` | false | true | false | true | Calls configured AI, creates a resume and replaces the application’s linked resume with timeline activity; repeats create more work. |
+| `draft_application_message` | false | false | false | true | Calls configured AI; cover-letter mode creates a private letter, follow-up mode returns text only; repeats can create letters; sends nothing to an employer. |
+
+## API tools
+
+| Tool | R | D | I | O | Behavior justification |
+| --------------------------------------- | ----- | ----- | ----- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api_resume_list_versions` | true | false | true | false | Reads owned resume history without writes or external calls. |
+| `api_resume_get_version` | true | false | true | false | Reads an owned resume snapshot without writes or external calls. |
+| `api_resume_create_version` | false | false | false | false | Adds a named snapshot; repeated calls can add snapshots within the account. |
+| `api_resume_rename_version` | false | true | false | false | Replaces an existing snapshot name within the account. |
+| `api_resume_delete_version` | false | true | false | false | Deletes a named snapshot from account history. |
+| `api_resume_restore_version` | false | true | false | true | Replaces resume data and adds restore history; public viewers can see changed content; repeats can add history. |
+| `api_resume_remove_password` | false | true | false | true | Removes protection and emits a document update; public viewers gain access without a password. |
+| `api_resume_get_by_slug` | false | false | false | true | Reads a public resume, possibly another account’s, and can increment view statistics; later visits can count again. |
+| `api_resume_check_slug` | true | false | true | false | Checks account slug availability without reserving it or changing data. |
+| `api_resume_update` | false | true | false | true | Replaces resume fields/content and adds history; can publish or change a public resume. |
+| `api_resume_statistics_get_daily_by_id` | true | false | true | false | Reads owned daily statistics without writes or external calls. |
+| `api_resume_statistics_record_download` | false | false | false | false | Records internal download statistics; repeats outside the deduplication window can increment again. |
+| `api_cover_letters_list_versions` | true | false | true | false | Reads owned letter history without writes or external calls. |
+| `api_cover_letters_get_version` | true | false | true | false | Reads an owned letter snapshot without writes or external calls. |
+| `api_cover_letters_create_version` | false | false | false | false | Adds a letter snapshot; repeated calls can add snapshots within the account. |
+| `api_cover_letters_rename_version` | false | true | false | false | Replaces an existing letter snapshot name within the account. |
+| `api_cover_letters_delete_version` | false | true | false | false | Deletes an owned named letter snapshot from account history. |
+| `api_cover_letters_restore_version` | false | true | false | false | Replaces letter content and saves restore points in the account; repeats can add history. |
+| `api_cover_letters_draft` | false | true | false | true | Calls configured AI with letter/resume/posting context; saves no draft; repeats issue new provider requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_documents_list` | false | true | false | false | Listing Trash can permanently purge expired documents and owned files; time passing can make more documents eligible. |
+| `api_documents_counts` | true | false | true | false | Counts account documents and Trash without purging or modifying them. |
+| `api_documents_rename` | false | true | false | false | Replaces an owned document name and updates its metadata. |
+| `api_documents_set_tags` | false | true | false | false | Replaces an owned document’s complete tag list and updates its metadata. |
+| `api_documents_set_locked` | false | true | false | false | Replaces document lock state; resume calls emit update notifications on each call. |
+| `api_documents_link_application` | false | true | false | false | Replaces or clears account document/application links and can replace an application’s working document. |
+| `api_documents_trash` | false | true | false | true | Writes a new Trash timestamp, hides the document and disables a resume’s public link. |
+| `api_documents_restore` | false | true | false | true | Replaces Trash state and updates metadata; restoring a public resume makes its link accessible again. |
+| `api_documents_purge` | false | true | false | false | Permanently deletes a trashed document and associated account data/files. |
+| `api_documents_purge_expired` | false | true | false | false | Permanently deletes expired Trash and associated owned data/files; eligibility changes with time. |
+| `api_documents_copy_for_job` | false | true | false | false | Creates a resume copy and can replace an application’s working resume link; repeats create more copies within the account. |
+| `api_applications_ai_search_postings` | false | true | false | true | Queries external search services for public jobs without saving applications; repeats issue new requests. Can initialize/replace saved career search-region preferences from the device timezone. |
+| `api_applications_ai_parse_posting` | false | true | false | true | Can fetch a public posting and call configured AI; returns fields without saving applications; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_ai_parse_pdf` | false | true | false | true | Sends PDF content to configured AI; returns data without saving a resume; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_ai_parse_docx` | false | true | false | true | Sends Word content to configured AI; returns data without saving a resume; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_ai_ats_review` | false | true | false | true | Sends resume text/posting to configured AI; returns feedback without saving edits; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_ai_improve` | false | true | false | true | Sends supplied text to configured AI; returns a suggestion without saving edits; repeats issue new requests. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_ai_providers_list` | false | true | false | false | Lists redacted settings and can upsert/replace a server-managed provider record; no external provider call. |
+| `api_ai_providers_delete` | false | true | false | false | Deletes account provider configuration and may affect linked assistant records; does not contact the provider. |
+| `api_ai_providers_test` | false | true | false | true | Calls configured AI and overwrites enabled/test status with a fresh timestamp; repeats run another test. |
+| `api_ai_providers_set_default` | false | true | false | false | Replaces account provider defaults and updates existing records without contacting the provider. |
+| `api_web_access_status` | true | false | true | false | Reads configured web availability without probing external search or pages. |
+| `api_web_access_delete` | false | true | false | false | Deletes the account’s saved web connection without contacting the external service. |
+| `api_web_access_test` | false | true | false | true | Probes external search/reading services without saving documents; repeats issue new requests. Can initialize/replace saved career search-region preferences from the device timezone. |
+| `api_agent_threads_list` | true | false | true | false | Reads account conversation summaries without model calls or writes. |
+| `api_agent_threads_start` | false | true | false | false | Creates an account conversation/provider reference without generating a reply; repeats can add conversations. Server-managed AI can upsert/replace the account provider record, so this is conservatively classified as a destructive write even without saving generated document content. |
+| `api_agent_threads_get` | false | true | false | false | Reads conversation data but can reap a stale run, clearing its claim and settling persisted message state; time-dependent cleanup stays within the account and calls no AI provider. |
+| `api_agent_threads_update` | false | true | false | false | Replaces owned conversation settings/title without a model call. |
+| `api_agent_threads_delete` | false | true | false | false | Deletes an owned conversation and associated data/files without a model call. |
+| `api_agent_messages_send` | false | true | false | true | Persists messages/run state and can update career memory or existing messages; sends selected context to AI and may search public pages; repeats can generate more work. |
+| `api_agent_messages_stop` | false | true | false | false | Cancels a run and can persist partial content or reap stale state within the account; starts no model call. |
+| `api_agent_messages_resume` | true | false | true | false | Reconnects to an existing server-side stream; does not restart generation or call a provider. |
+| `api_agent_messages_set_edit_status` | false | true | false | false | Replaces edit statuses and conversation acceptance counts within the account; does not apply document edits or call AI. |
+| `api_agent_attachments_create` | false | false | false | false | Creates a private attachment record/file; sends nothing to AI until a later message; repeats can add attachments. |
+| `api_agent_attachments_delete` | false | true | false | false | Deletes a private account attachment/file without a provider call or publication. |
+| `api_career_profile` | true | false | true | false | Reads account career preferences without writes or external calls. |
+| `api_career_save_profile` | false | true | false | false | Replaces account career preferences and updates their timestamp; runs no coaching/search. |
+| `api_career_facts` | true | false | true | false | Reads owned facts and usage metadata without writes or external calls. |
+| `api_career_save_fact` | false | false | false | false | Adds an evidence-backed account fact with source deduplication; no general retry guarantee is advertised. |
+| `api_career_update_fact` | false | true | false | false | Replaces fact fields, can append correction history and invalidates dependent account work. |
+| `api_career_forget_fact` | false | true | false | false | Erases fact text, quotation/history and unlinks dependent account data. |
+| `api_career_stories` | true | false | true | false | Reads owned stories and supporting facts without writes or external calls. |
+| `api_career_save_story` | false | true | false | false | Creates or replaces an owned story; repeats without an id can add stories. |
+| `api_career_delete_story` | false | true | false | false | Deletes an owned story while keeping supporting facts; no external calls. |
+| `api_career_saved_items` | true | false | true | false | Reads saved account coaching work without regenerating it or calling AI. |
+| `api_career_delete_saved_item` | false | true | false | false | Deletes owned saved coaching work without external calls. |
+| `api_career_apply_reply` | false | true | false | false | Applies saved suggestions to application fields or offer records and can add history; sends no employer message. |
+| `api_career_workspace` | true | false | true | false | Reads an owned application workspace without writes or external calls. |
+| `api_career_save_workspace` | false | true | false | false | Replaces workspace keys with concurrency checks within the account; stale repeats can conflict. |
+| `api_career_schedules` | true | false | true | false | Reads account schedules without running jobs or sending notifications. |
+| `api_career_save_schedule` | false | true | false | true | Creates/replaces a schedule; enabled jobs can later call AI/search and send owner email; repeats without an id can add schedules. |
+| `api_career_delete_schedule` | false | true | false | false | Deletes an owned schedule and prevents future runs; performs no research or email sending. |
+| `api_career_opportunities` | true | false | true | false | Reads already-discovered account opportunities without new external searches. |
+| `api_career_dismiss_opportunity` | false | true | false | false | Updates dismissal state of an owned opportunity without external calls. |
+| `api_career_track_opportunity` | false | false | true | false | Creates one account application under a row lock; repeats return the same application id without another creation; no external calls. |
+| `api_career_notifications` | true | false | true | false | Reads account notifications without sending them or marking them read. |
+| `api_career_mark_notification_read` | false | true | false | false | Replaces a notification’s read timestamp on each call within the account; sends nothing. |
+| `api_auth_providers_list` | true | false | true | false | Reads configured sign-in provider availability without authenticating with external providers. |
+| `api_auth_export_data` | true | false | true | false | Returns account export data without changing it or sending it to another service. |
+| `api_flags_get` | true | false | true | false | Reads server feature flags without writes or external calls. |
+| `api_statistics_get_totals` | true | false | true | false | Reads aggregate Reactive Resume statistics without writes or external calls. |
+| `api_statistics_github_get_star_count` | true | false | false | true | Reads public repository star count from GitHub with caching; may issue new external requests; changes no user data. |
+| `api_storage_delete_file` | false | true | false | true | Deletes an owned stored file, possibly a public profile picture, removing access through its URL. |
+| `api_rest_document_exports_resume` | true | false | true | false | Checks ownership and returns an authenticated download URL only; does not render, upload, record downloads or fetch external assets during this tool call. |
+| `api_rest_document_exports_letter` | true | false | true | false | Checks ownership and returns an authenticated download URL only; does not render, upload or fetch external assets during this tool call. |
+| `api_rest_check_resume` | true | false | true | false | Runs deterministic checks on an owned resume without saving edits, AI or external search. |
+| `api_rest_check_pdf` | true | false | true | false | Extracts/analyzes supplied PDF locally without saving it, AI or external services. |
+| `api_rest_match_resume` | true | false | true | false | Matches supplied posting terms to an owned resume locally without saving edits, AI or external search. |
+| `api_rest_import_resume_file` | false | false | false | false | Parses supplied file locally and creates a private resume; repeats add resumes; no AI or remote import source. |
+| `api_rest_file_upload` | false | false | false | true | Stores a new owned file; images become public profile pictures, other files stay private; repeats can add files. |
+
+## Browser handoffs
+
+| Tool | R | D | I | O | Behavior justification |
+| ---------------------------- | ---- | ----- | ---- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api_ai_providers_create` | true | false | true | false | Returns an app settings URL for adding a provider; stores no credentials or configuration. Repeating only returns a URL; no external request is made. |
+| `api_ai_providers_update` | true | false | true | false | Returns an app settings URL for editing a provider; stores no credentials or configuration. Repeating only returns a URL; no external request is made. |
+| `api_web_access_save` | true | false | true | false | Returns an app settings URL for web setup; saves no web connection. Repeating only returns a URL; no external request is made. |
+| `api_resume_get_root` | true | false | true | false | Returns a dashboard URL; does not create or modify the root resume. Repeating only returns a URL; no external request is made. |
+| `api_auth_create_api_key` | true | false | true | false | Returns an API-key settings URL; creates no API key. Repeating only returns a URL; no external request is made. |
+| `api_auth_delete_account` | true | false | true | false | Returns an account settings URL; deletes no account or data. Repeating only returns a URL; no external request is made. |
+| `api_resume_set_password` | true | false | true | false | Returns an editor URL; sets no password and changes no sharing state. Repeating only returns a URL; no external request is made. |
+| `api_resume_verify_password` | true | false | true | false | Returns a public resume URL; verifies no password and grants no access. Repeating only returns a URL; no external request is made. |
+| `open_account_settings` | true | false | true | false | Returns the selected account settings URL only; authentication/security actions require later browser interaction. Repeating only returns a URL; no external request is made. |
diff --git a/packages/mcp/src/annotations.ts b/packages/mcp/src/annotations.ts
new file mode 100644
index 000000000..cad78b259
--- /dev/null
+++ b/packages/mcp/src/annotations.ts
@@ -0,0 +1,47 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+
+export type BehaviorAnnotations = ToolAnnotations &
+ Required<Pick<ToolAnnotations, "readOnlyHint" | "destructiveHint" | "idempotentHint" | "openWorldHint">>;
+
+export const READ_IDEMPOTENT: BehaviorAnnotations = {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+};
+export const READ_EXTERNAL: BehaviorAnnotations = {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: false,
+ openWorldHint: true,
+};
+export const WRITE_NON_IDEMPOTENT: BehaviorAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: false,
+ idempotentHint: false,
+ openWorldHint: false,
+};
+export const WRITE_DESTRUCTIVE: BehaviorAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: true,
+ idempotentHint: false,
+ openWorldHint: false,
+};
+export const WRITE_IDEMPOTENT: BehaviorAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+};
+export const WRITE_EXTERNAL: BehaviorAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: false,
+ idempotentHint: false,
+ openWorldHint: true,
+};
+export const WRITE_DESTRUCTIVE_EXTERNAL: BehaviorAnnotations = {
+ readOnlyHint: false,
+ destructiveHint: true,
+ idempotentHint: false,
+ openWorldHint: true,
+};
diff --git a/packages/mcp/src/parity.test.ts b/packages/mcp/src/parity.test.ts
index 8705b3628..6e27cd183 100644
--- a/packages/mcp/src/parity.test.ts
+++ b/packages/mcp/src/parity.test.ts
@@ -71,9 +71,11 @@ it("hands account deletion to browser settings without invoking the API", async
it("discovers API-derived contracts and exchanges native files and dates through the SDK", async () => {
const { tools } = await client.listTools();
const cardTools = new Map(buildMcpServerCard("1.0.0").tools.map((tool) => [tool.name, tool]));
+ expect(tools.map((tool) => tool.name).sort()).toEqual([...cardTools.keys()].sort());
for (const tool of tools) {
expect(tool.inputSchema, tool.name).toEqual(cardTools.get(tool.name)?.inputSchema);
expect(tool.outputSchema, tool.name).toEqual(cardTools.get(tool.name)?.outputSchema);
+ expect(tool.annotations, tool.name).toEqual(cardTools.get(tool.name)?.annotations);
}
expect(tools.find((tool) => tool.name === "api_resume_list_versions")?.outputSchema).toBeDefined();
expect(tools.find((tool) => tool.name === "update_resume")?.inputSchema.properties?.data).toBeDefined();
diff --git a/packages/mcp/src/parity.ts b/packages/mcp/src/parity.ts
index 55ab25cd9..b976c812a 100644
--- a/packages/mcp/src/parity.ts
+++ b/packages/mcp/src/parity.ts
@@ -1,5 +1,5 @@
+import type { BehaviorAnnotations } from "./annotations";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
import type { AnyProcedure, InferRouterInitialContext, RouterClient } from "@orpc/server";
import type { RequestAuthentication } from "@reactive-resume/api/context";
import { call, ORPCError } from "@orpc/server";
@@ -8,6 +8,15 @@ import { requiredPermission } from "@reactive-resume/api/context";
import { restAliases } from "@reactive-resume/api/rest";
import router from "@reactive-resume/api/routers";
import { env } from "@reactive-resume/env/server";
+import {
+ READ_EXTERNAL,
+ READ_IDEMPOTENT,
+ WRITE_DESTRUCTIVE,
+ WRITE_DESTRUCTIVE_EXTERNAL,
+ WRITE_EXTERNAL,
+ WRITE_IDEMPOTENT,
+ WRITE_NON_IDEMPOTENT,
+} from "./annotations";
import { fileInputSchema, toWireObjectSchema, wireJsonSchema } from "./contracts";
import { readMcpFile } from "./files";
import { json, withErrorHandling } from "./results";
@@ -116,39 +125,101 @@ function parityToolName(path: string): string {
}
const streamingPaths = new Set(["coverLetters.draft", "agent.messages.send", "agent.messages.resume"]);
-const readOnlyPosts = new Set([
- "ai.parsePdf",
- "ai.parseDocx",
- "ai.atsReview",
- "ai.improve",
- "applications.ai.searchPostings",
- "applications.ai.parsePosting",
- "rest.checkResume",
- "rest.checkPdf",
- "rest.matchResume",
- "coverLetters.draft",
- "webAccess.test",
-]);
const exportPaths = new Set(["rest.documentExports.resume", "rest.documentExports.letter"]);
-const destructiveWrites = new Set([
- "career.saveProfile",
- "career.saveStory",
- "career.saveSchedule",
- "career.saveWorkspace",
- "career.applyReply",
- "agent.messages.stop",
-]);
-// Changes what a public resume link or uploaded file URL shows, or sends content to the user's AI provider.
-const openWorldPaths = new Set([
- "resume.update",
- "resume.restoreVersion",
- "resume.removePassword",
- "rest.fileUpload",
- "coverLetters.draft",
- "career.saveSchedule",
- "agent.messages.send",
- "statistics.github.getStarCount",
-]);
+
+// Behavior is explicit: HTTP methods and names miss cleanup, publication and provider calls.
+// Per-tool justifications: .agents/docs/mcp-tool-annotations.md.
+const PARITY_ANNOTATIONS = {
+ "resume.listVersions": READ_IDEMPOTENT,
+ "resume.getVersion": READ_IDEMPOTENT,
+ "resume.createVersion": WRITE_NON_IDEMPOTENT,
+ "resume.renameVersion": WRITE_DESTRUCTIVE,
+ "resume.deleteVersion": WRITE_DESTRUCTIVE,
+ "resume.restoreVersion": WRITE_DESTRUCTIVE_EXTERNAL,
+ "resume.removePassword": WRITE_DESTRUCTIVE_EXTERNAL,
+ "resume.getBySlug": WRITE_EXTERNAL,
+ "resume.checkSlug": READ_IDEMPOTENT,
+ "resume.update": WRITE_DESTRUCTIVE_EXTERNAL,
+ "resume.statistics.getDailyById": READ_IDEMPOTENT,
+ "resume.statistics.recordDownload": WRITE_NON_IDEMPOTENT,
+ "coverLetters.listVersions": READ_IDEMPOTENT,
+ "coverLetters.getVersion": READ_IDEMPOTENT,
+ "coverLetters.createVersion": WRITE_NON_IDEMPOTENT,
+ "coverLetters.renameVersion": WRITE_DESTRUCTIVE,
+ "coverLetters.deleteVersion": WRITE_DESTRUCTIVE,
+ "coverLetters.restoreVersion": WRITE_DESTRUCTIVE,
+ "coverLetters.draft": WRITE_DESTRUCTIVE_EXTERNAL,
+ "documents.list": WRITE_DESTRUCTIVE,
+ "documents.counts": READ_IDEMPOTENT,
+ "documents.rename": WRITE_DESTRUCTIVE,
+ "documents.setTags": WRITE_DESTRUCTIVE,
+ "documents.setLocked": WRITE_DESTRUCTIVE,
+ "documents.linkApplication": WRITE_DESTRUCTIVE,
+ "documents.trash": WRITE_DESTRUCTIVE_EXTERNAL,
+ "documents.restore": WRITE_DESTRUCTIVE_EXTERNAL,
+ "documents.purge": WRITE_DESTRUCTIVE,
+ "documents.purgeExpired": WRITE_DESTRUCTIVE,
+ "documents.copyForJob": WRITE_DESTRUCTIVE,
+ "applications.ai.searchPostings": WRITE_DESTRUCTIVE_EXTERNAL,
+ "applications.ai.parsePosting": WRITE_DESTRUCTIVE_EXTERNAL,
+ "ai.parsePdf": WRITE_DESTRUCTIVE_EXTERNAL,
+ "ai.parseDocx": WRITE_DESTRUCTIVE_EXTERNAL,
+ "ai.atsReview": WRITE_DESTRUCTIVE_EXTERNAL,
+ "ai.improve": WRITE_DESTRUCTIVE_EXTERNAL,
+ "aiProviders.list": WRITE_DESTRUCTIVE,
+ "aiProviders.delete": WRITE_DESTRUCTIVE,
+ "aiProviders.test": WRITE_DESTRUCTIVE_EXTERNAL,
+ "aiProviders.setDefault": WRITE_DESTRUCTIVE,
+ "webAccess.status": READ_IDEMPOTENT,
+ "webAccess.delete": WRITE_DESTRUCTIVE,
+ "webAccess.test": WRITE_DESTRUCTIVE_EXTERNAL,
+ "agent.threads.list": READ_IDEMPOTENT,
+ "agent.threads.start": WRITE_DESTRUCTIVE,
+ "agent.threads.get": WRITE_DESTRUCTIVE,
+ "agent.threads.update": WRITE_DESTRUCTIVE,
+ "agent.threads.delete": WRITE_DESTRUCTIVE,
+ "agent.messages.send": WRITE_DESTRUCTIVE_EXTERNAL,
+ "agent.messages.stop": WRITE_DESTRUCTIVE,
+ "agent.messages.resume": READ_IDEMPOTENT,
+ "agent.messages.setEditStatus": WRITE_DESTRUCTIVE,
+ "agent.attachments.create": WRITE_NON_IDEMPOTENT,
+ "agent.attachments.delete": WRITE_DESTRUCTIVE,
+ "career.profile": READ_IDEMPOTENT,
+ "career.saveProfile": WRITE_DESTRUCTIVE,
+ "career.facts": READ_IDEMPOTENT,
+ "career.saveFact": WRITE_NON_IDEMPOTENT,
+ "career.updateFact": WRITE_DESTRUCTIVE,
+ "career.forgetFact": WRITE_DESTRUCTIVE,
+ "career.stories": READ_IDEMPOTENT,
+ "career.saveStory": WRITE_DESTRUCTIVE,
+ "career.deleteStory": WRITE_DESTRUCTIVE,
+ "career.savedItems": READ_IDEMPOTENT,
+ "career.deleteSavedItem": WRITE_DESTRUCTIVE,
+ "career.applyReply": WRITE_DESTRUCTIVE,
+ "career.workspace": READ_IDEMPOTENT,
+ "career.saveWorkspace": WRITE_DESTRUCTIVE,
+ "career.schedules": READ_IDEMPOTENT,
+ "career.saveSchedule": WRITE_DESTRUCTIVE_EXTERNAL,
+ "career.deleteSchedule": WRITE_DESTRUCTIVE,
+ "career.opportunities": READ_IDEMPOTENT,
+ "career.dismissOpportunity": WRITE_DESTRUCTIVE,
+ "career.trackOpportunity": WRITE_IDEMPOTENT,
+ "career.notifications": READ_IDEMPOTENT,
+ "career.markNotificationRead": WRITE_DESTRUCTIVE,
+ "auth.providers.list": READ_IDEMPOTENT,
+ "auth.exportData": READ_IDEMPOTENT,
+ "flags.get": READ_IDEMPOTENT,
+ "statistics.getTotals": READ_IDEMPOTENT,
+ "statistics.github.getStarCount": READ_EXTERNAL,
+ "storage.deleteFile": WRITE_DESTRUCTIVE_EXTERNAL,
+ "rest.documentExports.resume": READ_IDEMPOTENT,
+ "rest.documentExports.letter": READ_IDEMPOTENT,
+ "rest.checkResume": READ_IDEMPOTENT,
+ "rest.checkPdf": READ_IDEMPOTENT,
+ "rest.matchResume": READ_IDEMPOTENT,
+ "rest.importResumeFile": WRITE_NON_IDEMPOTENT,
+ "rest.fileUpload": WRITE_EXTERNAL,
+} satisfies Record<keyof typeof PARITY_PROCEDURES, BehaviorAnnotations>;
/** These workflows require browser interaction so secrets and security ceremonies stay with the user. */
const BROWSER_HANDOFFS = {
@@ -191,14 +262,14 @@ const RESUME_PASSWORD_HANDOFFS = {
},
};
-const handoffAnnotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const handoffAnnotations = READ_IDEMPOTENT;
const handoffOutputSchema = z.object({ url: z.url(), action: z.string(), requiresBrowser: z.literal(true) });
type HandoffToolMeta = {
title: string;
description: string;
inputSchema: z.ZodObject;
outputSchema: typeof handoffOutputSchema;
- annotations: ToolAnnotations;
+ annotations: BehaviorAnnotations;
};
// Directories show annotations.title as the tool's name, so every tool repeats its title there.
const handoffMeta = (path: string, description: string, inputSchema: z.ZodObject): HandoffToolMeta => {
@@ -304,14 +375,12 @@ export const PARITY_TOOL_META: Record<
Pick<ReturnType<typeof parityToolContract>, "inputSchema" | "outputSchema"> & {
title: string;
description: string;
- annotations: ToolAnnotations;
+ annotations: BehaviorAnnotations;
}
> = {
...Object.fromEntries(
Object.entries(PARITY_PROCEDURES).map(([path, procedure]) => {
const route = procedure["~orpc"].route;
- const readOnly =
- (route.method === "GET" || readOnlyPosts.has(path)) && !["resume.getBySlug", "aiProviders.list"].includes(path);
const contract = parityToolContract(path, procedure);
const title = route.summary ?? path;
return [
@@ -323,15 +392,7 @@ export const PARITY_TOOL_META: Record<
outputSchema: contract.outputSchema,
annotations: {
title,
- readOnlyHint: readOnly,
- destructiveHint:
- !readOnly &&
- (route.method === "DELETE" ||
- destructiveWrites.has(path) ||
- /update|delete|purge|remove|restore|password|trash|set/i.test(path)),
- idempotentHint: readOnly && !/draft|parse|test|search|improve|review/i.test(path),
- openWorldHint:
- openWorldPaths.has(path) || /ai|webAccess|storage|attachments|Exports|importResumeFile/i.test(path),
+ ...PARITY_ANNOTATIONS[path as keyof typeof PARITY_ANNOTATIONS],
},
},
];
diff --git a/packages/mcp/src/tool-annotations.test.ts b/packages/mcp/src/tool-annotations.test.ts
index dc684b0a3..af637e24c 100644
--- a/packages/mcp/src/tool-annotations.test.ts
+++ b/packages/mcp/src/tool-annotations.test.ts
@@ -1,8 +1,96 @@
+import { readFileSync } from "node:fs";
import { describe, expect, it } from "vite-plus/test";
import { MCP_TOOL_NAME } from "./mcp-tool-names";
+import { PARITY_TOOL_META } from "./parity";
import { TOOL_META } from "./tool-meta";
describe("tool annotations", () => {
+ it("keeps reviewer justifications aligned with every registered tool", () => {
+ const review = readFileSync(new URL("../../../.agents/docs/mcp-tool-annotations.md", import.meta.url), "utf8");
+ const rows = new Map(
+ [
+ ...review.matchAll(
+ /^\| `([^`]+)` +\| (true|false) +\| (true|false) +\| (true|false) +\| (true|false) +\| (.+?) +\|$/gm,
+ ),
+ ].map(
+ ([, name, readOnly, destructive, idempotent, openWorld, reason]) =>
+ [
+ name,
+ {
+ annotations: {
+ readOnlyHint: readOnly === "true",
+ destructiveHint: destructive === "true",
+ idempotentHint: idempotent === "true",
+ openWorldHint: openWorld === "true",
+ },
+ reason,
+ },
+ ] as const,
+ ),
+ );
+ const tools = { ...TOOL_META, ...PARITY_TOOL_META };
+ expect([...rows.keys()].sort()).toEqual(Object.keys(tools).sort());
+ for (const [name, tool] of Object.entries(tools)) {
+ const row = rows.get(name);
+ expect(tool.annotations, name).toMatchObject(row?.annotations ?? {});
+ expect(row?.reason?.length, name).toBeGreaterThan(40);
+ }
+ });
+
+ it("declares all four behavior hints as booleans for every tool", () => {
+ for (const [name, tool] of Object.entries({ ...TOOL_META, ...PARITY_TOOL_META })) {
+ for (const hint of ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] as const) {
+ expect(typeof tool.annotations[hint], `${name}.${hint}`).toBe("boolean");
+ }
+ }
+ });
+
+ it("accounts for destructive effects hidden behind list, rename, copy and test operations", () => {
+ for (const name of [
+ "api_documents_list",
+ "api_documents_rename",
+ "api_documents_link_application",
+ "api_documents_copy_for_job",
+ "api_resume_rename_version",
+ "api_cover_letters_rename_version",
+ "api_ai_providers_test",
+ "api_agent_threads_get",
+ "api_ai_parse_pdf",
+ "api_web_access_test",
+ "api_applications_ai_search_postings",
+ ]) {
+ expect(PARITY_TOOL_META[name]?.annotations, name).toMatchObject({ readOnlyHint: false, destructiveHint: true });
+ }
+ });
+
+ it("distinguishes internal operations from external AI, search and public sharing", () => {
+ for (const name of [
+ "api_web_access_status",
+ "api_web_access_delete",
+ "api_ai_providers_list",
+ "api_ai_providers_delete",
+ "api_ai_providers_set_default",
+ "api_agent_messages_resume",
+ "api_agent_attachments_create",
+ "api_rest_document_exports_resume",
+ "api_rest_document_exports_letter",
+ "api_rest_check_pdf",
+ "api_rest_match_resume",
+ "api_rest_import_resume_file",
+ ]) {
+ expect(PARITY_TOOL_META[name]?.annotations.openWorldHint, name).toBe(false);
+ }
+ for (const name of [
+ "api_agent_messages_send",
+ "api_applications_ai_search_postings",
+ "api_resume_get_by_slug",
+ "api_documents_trash",
+ "api_documents_restore",
+ ]) {
+ expect(PARITY_TOOL_META[name]?.annotations.openWorldHint, name).toBe(true);
+ }
+ });
+
it("marks tools that replace or remove existing data as destructive", () => {
for (const name of [
MCP_TOOL_NAME.patchResume,
@@ -21,6 +109,7 @@ describe("tool annotations", () => {
MCP_TOOL_NAME.updateCoverLetter,
MCP_TOOL_NAME.refreshCoverLetterStyle,
MCP_TOOL_NAME.deleteCoverLetter,
+ MCP_TOOL_NAME.autofillApplicationFromJob,
]) {
expect(TOOL_META[name].annotations.readOnlyHint, name).toBe(false);
expect(TOOL_META[name].annotations.destructiveHint, name).toBe(true);
diff --git a/packages/mcp/src/tool-meta.ts b/packages/mcp/src/tool-meta.ts
index dc73912f2..c08063b18 100644
--- a/packages/mcp/src/tool-meta.ts
+++ b/packages/mcp/src/tool-meta.ts
@@ -2,7 +2,7 @@
* Canonical tool metadata (title, description, inputSchema, annotations) declared once.
* Consumed by both `registerTools` (raw Zod) and `buildMcpServerCard` (toJsonSchemaCompat).
*/
-import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { BehaviorAnnotations } from "./annotations";
import z from "zod";
import { resumePatchOperationsSchema } from "@reactive-resume/ai/tools/resume-tool-contracts";
import { applicationDto } from "@reactive-resume/api/dto/application";
@@ -17,11 +17,20 @@ import {
} from "@reactive-resume/schema/applications/data";
import { coverLetterDocumentSchema } from "@reactive-resume/schema/cover-letter/data";
import { templateSchema } from "@reactive-resume/schema/templates";
+import { READ_IDEMPOTENT, WRITE_DESTRUCTIVE_EXTERNAL, WRITE_NON_IDEMPOTENT, WRITE_DESTRUCTIVE } from "./annotations";
import { toWireObjectSchema, toWireSchema } from "./contracts";
import { MCP_TOOL_NAME as T } from "./mcp-tool-names";
// Contracts remain derived from the allowlisted API procedures in parity.ts.
export const PARITY_TOOL_DESCRIPTIONS: Record<string, string> = {
+ "documents.list":
+ "List owned resumes and cover letters, optionally from Trash. Listing Trash also permanently purges documents older than 30 days and their owned files.",
+ "aiProviders.list":
+ "List saved AI providers with redacted credentials. When AI is server-managed, synchronize the account's managed provider record with server configuration. Does not contact an AI provider.",
+ "aiProviders.test":
+ "Test the saved provider/model connection server-side, then replace its saved test status and timestamp and enable or disable the connection based on the result.",
+ "agent.threads.get":
+ "Read an owned conversation, messages and attachments. If its active run is stale, clear the dead run claim and settle its streaming message state before returning. Does not start generation or call an AI provider.",
"agent.threads.start":
"Start a document, application, or general career conversation using a tested saved AI provider. For scope=document, choose exactly one resumeId or coverLetterId. For scope=application, provide applicationId. For scope=career, omit document and application IDs.",
"career.profile":
@@ -49,7 +58,7 @@ export const PARITY_TOOL_DESCRIPTIONS: Record<string, string> = {
"career.workspace":
"Read an application's workspace: form answers, the submit checklist, questions to ask, evidence added from Fit, ticked plan rows and the pasted employer message.",
"coverLetters.draft":
- "Write a draft of a cover letter's body with the user's AI provider, from the letter's linked resume and its application's job posting, using only facts from them. Returns the draft text as chunks in `events` to join in order; `truncated` is true past 500,000 characters. Nothing is saved: write the draft into the letter with `update_cover_letter`. Use variant `shorter` or `personal` with `previous` to revise an earlier draft.",
+ "Write a draft of a cover letter's body with the user's AI provider, from the letter's linked resume and its application's job posting, using only facts from them. Returns the draft text as chunks in `events` to join in order; `truncated` is true past 500,000 characters. No letter content is saved; server-managed AI can synchronize its account provider record. Write the draft into the letter with `update_cover_letter`. Use variant `shorter` or `personal` with `previous` to revise an earlier draft.",
"career.saveWorkspace":
"Save parts of an application's workspace. Each key given replaces that whole key; keys left out keep their values.",
"career.trackOpportunity":
@@ -65,37 +74,6 @@ export const PARITY_TOOL_DESCRIPTIONS: Record<string, string> = {
"career.markNotificationRead": "Mark an owned career notification as read.",
};
-const READ_IDEMPOTENT: ToolAnnotations = {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
-};
-const READ_NON_IDEMPOTENT: ToolAnnotations = {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: false,
- openWorldHint: false,
-};
-const WRITE_NON_IDEMPOTENT: ToolAnnotations = {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: false,
- openWorldHint: false,
-};
-const WRITE_DESTRUCTIVE: ToolAnnotations = {
- readOnlyHint: false,
- destructiveHint: true,
- idempotentHint: false,
- openWorldHint: false,
-};
-const WRITE_IDEMPOTENT: ToolAnnotations = {
- readOnlyHint: false,
- destructiveHint: false,
- idempotentHint: true,
- openWorldHint: false,
-};
-
// ponytail: shared schema fragment; exported so server-card can re-use without re-importing
const resumeIdSchema = z.string().min(1).describe(`Resume ID. Use \`${T.listResumes}\` to find valid IDs.`);
const applicationIdSchema = z
@@ -316,7 +294,7 @@ const BASE_TOOL_META = {
contentType: z.literal("application/pdf"),
}),
inputSchema: wireInput(z.strictObject({ id: resumeIdSchema })),
- annotations: READ_NON_IDEMPOTENT,
+ annotations: READ_IDEMPOTENT,
},
[T.createResume]: {
title: "Create Resume",
@@ -485,14 +463,14 @@ const BASE_TOOL_META = {
].join("\n"),
outputSchema: messageOutput,
inputSchema: wireInput(z.strictObject({ id: resumeIdSchema })),
- annotations: WRITE_IDEMPOTENT,
+ annotations: WRITE_DESTRUCTIVE,
},
[T.unlockResume]: {
title: "Unlock Resume",
description: "Unlock a previously locked resume, re-enabling edits, patches, and deletion.",
outputSchema: messageOutput,
inputSchema: wireInput(z.strictObject({ id: resumeIdSchema })),
- annotations: WRITE_IDEMPOTENT,
+ annotations: WRITE_DESTRUCTIVE,
},
[T.getResumeStatistics]: {
title: "Get Resume Statistics",
@@ -634,7 +612,7 @@ const BASE_TOOL_META = {
].join("\n"),
outputSchema: messageOutput,
inputSchema: wireInput(z.strictObject({ id: coverLetterIdSchema, expectedRevision: expectedRevisionSchema })),
- annotations: { ...WRITE_DESTRUCTIVE, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE,
},
[T.exportCoverLetter]: {
title: "Export Cover Letter",
@@ -797,7 +775,7 @@ const BASE_TOOL_META = {
"Permanently delete one job application and its owned uploaded documents that no remaining application references, removing those authenticated file URLs.",
outputSchema: messageOutput,
inputSchema: wireInput(z.strictObject({ id: applicationIdSchema })),
- annotations: { ...WRITE_DESTRUCTIVE, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE,
},
[T.bulkUpdateApplications]: {
title: "Bulk Update Applications",
@@ -819,7 +797,7 @@ const BASE_TOOL_META = {
"Permanently delete multiple applications and their owned uploaded documents that no remaining application references, removing those authenticated file URLs.",
outputSchema: toWireObjectSchema(applicationDto.bulkDelete.output),
inputSchema: wireInput(z.strictObject({ ids: z.array(z.string()).min(1) })),
- annotations: { ...WRITE_DESTRUCTIVE, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE,
},
[T.importApplications]: {
title: "Import Applications",
@@ -852,7 +830,7 @@ const BASE_TOOL_META = {
"Supply exactly one of dataBase64 or storagePath.",
),
),
- annotations: { ...WRITE_NON_IDEMPOTENT, destructiveHint: true, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE,
},
[T.removeApplicationDocument]: {
title: "Remove Application Document",
@@ -860,15 +838,15 @@ const BASE_TOOL_META = {
"Clear a resume or cover-letter attachment and delete its owned uploaded file if no other application references it, removing access through its authenticated file URL.",
outputSchema: toWireObjectSchema(applicationDto.removeDocument.output),
inputSchema: wireInput(z.strictObject({ id: applicationIdSchema, kind: applicationDocumentKindSchema })),
- annotations: { ...WRITE_DESTRUCTIVE, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE,
},
[T.autofillApplicationFromJob]: {
title: "Autofill Application From Job",
description:
- "Send a pasted job posting to your configured AI provider to extract company, role, location, and salary. Requires an enabled, tested default AI provider. Returns suggestions without saving an application or fetching a job URL.",
+ "Send a pasted job posting to your configured AI provider to extract company, role, location, and salary. Requires an enabled, tested default AI provider. Returns suggestions without saving an application or fetching a job URL. Server-managed AI can synchronize its account provider record.",
outputSchema: z.object({ company: z.string(), role: z.string(), location: z.string(), salary: z.string() }),
inputSchema: wireInput(z.strictObject({ jobDescription: z.string().trim().min(1).max(20_000) })),
- annotations: { ...READ_NON_IDEMPOTENT, openWorldHint: true },
+ annotations: WRITE_DESTRUCTIVE_EXTERNAL,
},
[T.scoreApplicationMatch]: {
title: "Score Application Match",
@@ -913,7 +891,9 @@ const applicationDateFields = {
};
// Shared DTOs keep fields, validation and limits aligned with API contracts.
// Directories show annotations.title as the tool's name, so every tool repeats its title there.
-function withAnnotationTitles<T extends Record<string, { title: string; annotations: ToolAnnotations }>>(meta: T): T {
+function withAnnotationTitles<T extends Record<string, { title: string; annotations: BehaviorAnnotations }>>(
+ meta: T,
+): T {
return Object.fromEntries(
Object.entries(meta).map(([name, tool]) => [
name,