Person Parameters
Let a tool take people instead of email addresses, so the model never holds an address and can only name people the caller can already see.
A tool that sends mail or invites people to a meeting needs their email
addresses. Declare its recipient params as person:email and the model never
has to know one: it names a person by the id List message recipients
returns, and Scrydon puts in that person's address when the call reaches your
tool.
Declare a person param
Give the param type: PERSON_PARAMETER_TYPES.EMAIL and keep its input field a
string. Put PERSON_EMAIL_PARAMETER_DESCRIPTION on both the param and the input
field's .describe(): only the input field's description reaches the model.
import {
defineTool,
PERSON_EMAIL_PARAMETER_DESCRIPTION,
PERSON_PARAMETER_TYPES,
} from "@scrydon/sdk-authoring/extensions/define";
import { z } from "zod";
const sendMail = defineTool({
id: "send-mail",
name: "Send mail",
description: "Sends an email.",
input: z.object({
to: z.string().describe(PERSON_EMAIL_PARAMETER_DESCRIPTION),
cc: z.string().optional().describe(PERSON_EMAIL_PARAMETER_DESCRIPTION),
subject: z.string(),
body: z.string(),
}),
params: {
to: {
type: PERSON_PARAMETER_TYPES.EMAIL,
required: true,
visibility: "user-or-llm",
description: PERSON_EMAIL_PARAMETER_DESCRIPTION,
},
cc: {
type: PERSON_PARAMETER_TYPES.EMAIL,
visibility: "user-or-llm",
description: PERSON_EMAIL_PARAMETER_DESCRIPTION,
},
},
execute: async (input) => {
// input.to is "grace@acme.example, bob@partner.example": addresses only.
// ...
},
});Your tool's code is unchanged: it receives a comma-separated list of email addresses, as it would without the param type.
What the model may put in it
A person:email value is one string of comma-separated entries. Each entry is
either:
- a person's id, as List message recipients returns it, or
- an email address someone gave the model, which is passed through as written.
A list may mix the two. Its order is kept, and spaces around each entry are trimmed. A list holds at most 50 entries of at most 320 characters each.
What Scrydon does with it
Before your tool runs, Scrydon replaces each person id with that person's address. It does this only for people the calling person's own List message recipients would show in this conversation: in a shared workspace, the people on its roster; in a personal workspace, the organization's active members.
The address goes only to your tool. The model's own input, which is what the audit log, data-loss prevention and the approval card see, still holds the ids. If a data-loss prevention policy rewrites the value, the rewritten value is sent and no address is put in.
What the model reads back
The same rule works in the other direction. In a Cortex conversation, a tool's
output reaches the model with each address of a person the caller's own List
message recipients would show replaced by that person's id. A value such as
Grace Hopper <grace@acme.example> keeps the name and becomes
Grace Hopper <id>. Every other address is left as the tool returned it: an
address outside the organization, of someone off the shared workspace's roster,
or of an inactive member. Only a string value that is wholly an address, or a
name and an address, is changed. Free text and object keys are never changed.
Your tool's output is unchanged everywhere else: a workflow step, the run's logs and the audit log see what your tool returned. A failed call's output is never changed. If the lookup cannot run, or an output names more than 200 addresses, the model receives the output as your tool returned it.
A caller of the platform SDK asks for this view with outputView: "model" on
action.tools.execute:
const result = await platform.action.tools.execute({
toolId,
input,
idempotencyKey,
outputView: TOOL_OUTPUT_VIEWS.MODEL, // from '@scrydon/sdk/platform'
})Without outputView, the output is returned unchanged. The field is not
passed to your tool and is not part of the call's idempotency.
When a call is refused
| Code | When | What the model is told to do |
|---|---|---|
PERSON_REFERENCE_REQUIRED | An entry is neither a person id nor an email address — a bare name such as Nathan — or the list is over its bound | Look the person up with List message recipients and call again with their id |
PERSON_REFERENCE_UNRESOLVED | A person id cannot be reached from here: not on the shared workspace's roster, not an active member, in another organization, or unknown | Do not retry; ask for that person's email address |
One id that does not resolve refuses the whole call, before your tool runs. The refusal message is the same whatever the reason, so a refusal never tells anyone whether a person exists or where. Both codes are listed with the others in Tool Execution Errors.
What is recorded
Each resolved param writes one extension.person_reference.resolved audit
event holding the tool, the param name and how many ids and addresses it held.
A refusal writes extension.person_reference.refused with the tool and the
code. Neither records an address or a person id.