JobMojito

Ask a candidate for documents

request_candidate_documents

Destructive

[Document requests] Ask a candidate for up to 10 documents (certificate, reference letter, work sample...) with a message and due date. With notify (the default) the candidate is e-mailed. dry_run=true shows whether the e-mail would go out (will_send, not_requested, no_valid_email, suppressed) and stores nothing. documents[].source_field_id replaces one of the position's own file questions, as its form names it (form_cover_letter, custom_...); without it the request is a plain upload.

Every argument in full, with examples: get_tool_reference.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "candidate_id": "<candidate_id>",
      "documents": "<documents>"
    },
    "name": "request_candidate_documents"
  }
}

Input Schema

Name	Required	Description
`notify`	No	Default true: e-mail the candidate "Documents requested" now (and the one reminder after the due date). false: the request only shows on their application page.
`dry_run`	No	true: check everything and answer who would be e-mailed, without creating the request or sending anything.
`message`	No	Message to the candidate, at most 2000 characters.
`due_date`	No	Due date (YYYY-MM-DD), today or later. After it the candidate is reminded once by e-mail (when notify is true).
`documents`	Yes	The documents to ask for, 1 to 10.
`llm_model`	No	Your model id, e.g. "claude-opus-4-8"; "unknown" if unsure. For analytics.
`merchant_id`	No	Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.
`candidate_id`	Yes	The candidate to ask (the `id` of a list_candidates row).
`application_id`	No	Optional: the candidate's application this is for (an application `id` from get_candidate); the e-mail then names its position.
`conversation_id`	No	The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.

Output Schema

Name	Required	Description
`email`	Yes
`notify`	Yes
`dry_run`	Yes
`message`	No
`due_date`	No
`documents`	Yes
`request_id`	No
`position_id`	No
`candidate_id`	Yes
`position_name`	No
`application_id`	No
`candidate_name`	No
`candidate_email`	No
`_mcp_instructions`	No	Server-issued metadata for this conversation.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 9, 2026

changedInput schema / properties / documents / items / properties / source_field_id / pattern

Previous value: -"^(form_cover_letter|form_national_id|custom_[A-Za-z0-9_]{1,60})$"New value: +"^(form_cover_letter|custom_[A-Za-z0-9_]{1,60})$"

Changed2 schema fields changedNov 9, 2026

changedInput schema / properties / application_id / description

Previous value: -"Optional: the candidate's application this is for (position_result.id); the e-mail then names its position."New value: +"Optional: the candidate's application this is for (an application `id` from get_candidate); the e-mail then names its position."

changedInput schema / properties / candidate_id / description

Previous value: -"The candidate to ask (profile_interview.id)."New value: +"The candidate to ask (the `id` of a list_candidates row)."

Changed23 schema fields changedNov 9, 2026

removedInput schema / properties / documents / items / properties / description / description
```
Removed value: -"Explanation shown to the candidate, at most 500 characters."
```

removedInput schema / properties / documents / items / properties / required / description

Removed value: -"Default true. The request completes when every required document is uploaded."

removedInput schema / properties / documents / items / properties / source_field_id / description

Removed value: -"Optional: the position's file question this replaces: form_cover_letter, form_national_id or custom_<name>."

removedInput schema / properties / documents / items / properties / title / description

Removed value: -"What you ask for, as the candidate sees it (1 to 120 characters), e.g. \"Copy of your passport\"."

addedInput schema / properties / llm_model

Added value: +{
+  "description": "Your model id, e.g. \"claude-opus-4-8\"; \"unknown\" if unsure. For analytics.",
+  "type": "string"
+}

removedOutput schema / properties / application_id / description
```
Removed value: -"The application (position_result.id)."
```

removedOutput schema / properties / candidate_email / description

Removed value: -"The candidate's e-mail address, where the e-mail goes."

removedOutput schema / properties / candidate_id / description
```
Removed value: -"The candidate (profile_interview.id)."
```

removedOutput schema / properties / candidate_name / description

Removed value: -"Candidate's name, or e-mail when the name is empty."

removedOutput schema / properties / documents / description

Removed value: -"The documents as they are (or would be) stored."

removedOutput schema / properties / documents / items / properties / description / description
```
Removed value: -"Explanation."
```
removedOutput schema / properties / documents / items / properties / required / description
```
Removed value: -"Required."
```
removedOutput schema / properties / documents / items / properties / sequence_no / description
```
Removed value: -"Order, from 1."
```
removedOutput schema / properties / documents / items / properties / source_field_id / description
```
Removed value: -"File question it replaces."
```
removedOutput schema / properties / documents / items / properties / title / description
```
Removed value: -"Title, trimmed."
```

removedOutput schema / properties / dry_run / description

Removed value: -"true when nothing was created or sent."

removedOutput schema / properties / due_date / description
```
Removed value: -"The due date (YYYY-MM-DD)."
```

removedOutput schema / properties / email / description

Removed value: -"The \"Documents requested\" e-mail: will_send (sent now, or at the time the company scheduled), not_requested (notify false), no_valid_email (the candidate has no usable address), suppressed (the company set this e-mail to Do not send)."

removedOutput schema / properties / message / description
```
Removed value: -"The message, trimmed."
```

removedOutput schema / properties / notify / description

Removed value: -"Whether the candidate is to be e-mailed."

removedOutput schema / properties / position_id / description

Removed value: -"The application's position (position_def_set.id)."

removedOutput schema / properties / position_name / description

Removed value: -"The position's name, as the e-mail shows it."

removedOutput schema / properties / request_id / description

Removed value: -"The new request (profile_interview_document_request.id). Left out on a dry run."

AddedNov 8, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well past the annotations: it discloses that the candidate is e-mailed immediately and reminded once after the due date, that dry_run stores nothing and returns will_send/not_requested/no_valid_email/suppressed, and that source_field_id replaces one of the position's own file questions, which explains the destructiveHint. It also notes the admin/sub-merchant restriction on merchant_id and that conversation_id and llm_model are recorded for analytics.

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-loads the core action and scope, then layers the notify/dry_run semantics and the source_field_id caveat in a tight block, closing with a pointer to get_tool_reference for full argument detail. The bracketed "[Document requests]" prefix is slightly odd but harmless; the density is justified by the amount of distinct behavior conveyed.

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 10-parameter mutating, externally-visible tool, the description covers the side effects (e-mail plus reminder), the preview path, the destructive field-replacement behavior, permission constraints, and a pointer to the full reference. With an output schema present and 100% schema coverage, nothing an agent needs before invoking it is missing.

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

Parameters4/5

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 genuine meaning beyond the schema for the two hardest parameters: source_field_id's naming forms (form_cover_letter, custom_<name>) and its replace-a-file-question effect, plus the enumerated dry_run outcomes. The remaining parameters (llm_model, merchant_id, conversation_id, application_id) are already fully documented in the schema and get little extra explanation.

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

Purpose4/5

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

States a concrete verb and resource plus concrete scope limits ("up to 10 documents", "with a message and due date") and example document types, so the agent knows exactly what will happen. It differentiates the plain-upload case from the source_field_id case, but does not name or contrast the closer siblings such as update_document_request, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives clear operational context: notify=true is the default and emails the candidate plus one reminder, notify=false only surfaces the request on the application page, and dry_run=true previews without storing anything. It lacks explicit 'use this instead of X when Y' routing toward the sibling tools, but the when-to-use conditions for its own flags are unambiguous.

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

All JobMojito tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.