Skip to main content
Glama

read_status_emails

Read-onlyIdempotent

Read job-application emails and propose status updates; confirm each suggestion before any changes are recorded.

Instructions

Read emails about the person's applications (a "thank you for applying" confirmation, a rejection, an interview invitation or scheduling link, a take-home assignment, an offer, a recruiter's reply) and PROPOSE what changes; nothing is recorded. Search the person's mail first (e.g. their applications' companies, or "thank you for applying", "your application", "interview"), and pass each message in; jobwatch never needs a mail password. Present the proposals to the person and only call mark_job for the ones they confirm, with the proposal's mark_job arguments (status, add_note, next_step, follow_up). Returns proposals (key, company, title, current_status, suggested_status (null: only a note), kind, note, next_step, email (date, sender, subject), confidence, why, mark_job), unmatched (emails about no tracked application, with the company guessed: offer to add it with add_application, or say it's an application it can't tell apart), nothing_new (emails that add nothing: already recorded or already past that stage) and other (the count of emails that aren't about an application). A status only moves forward: a late confirmation for an application already interviewing is not a proposal. For job-alert emails use import_job_alerts.

Input Schema

NameRequiredDescriptionDefault
emailsYesThe emails about applications, one string each: the raw message (RFC822, as a mail connector's raw format gives it, base64url-encoded as from Gmail's API is fine too; best, since it names the sender and date) or just its HTML or plain-text body.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: nothing is recorded, no mail password is needed, and statuses only move forward (a late confirmation for an already-interviewing application is not a proposal). It also discloses the return buckets, which the absent output schema does not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the core propose-don't-record behavior, and the dense parentheticals each carry real information (return buckets, kind examples). It is long, but the length is justified by the missing output schema; minor tightening is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex classification tool with no output schema, the description fully specifies the return structure (proposals, unmatched, nothing_new, other) plus the follow-up action, so an agent has everything needed to call it and act on the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents the single 'emails' parameter including accepted formats (RFC822, base64url, HTML/plain body). The description only adds the workflow instruction to search mail first and pass each message in, which is context rather than additional parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (emails about applications), and enumerates the email kinds it handles (confirmation, rejection, interview invite, offer, recruiter reply). It also names a sibling it is not (import_job_alerts) so the agent can disambiguate 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow (search mail first, pass each message in), an explicit handoff condition (present proposals, only call mark_job for confirmed ones with the proposal's arguments), and an explicit exclusion (job-alert emails go to import_job_alerts). When/when-not/alternative are all covered.

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