> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetrident.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Scorers: Evaluate Agent Responses Your Way

> Write custom JavaScript scorer functions in the Trident dashboard to evaluate agent responses against your own quality and safety criteria.

Trident's built-in scanners catch well-known threat patterns — prompt injection, jailbreaks, sensitive data leakage — but your agents also have domain-specific requirements that only you can define. A customer-support agent should never acknowledge competitor outages. A legal research agent should always cite sources. A financial agent should never provide specific investment advice. Custom Scorers let you encode those rules as JavaScript functions that run automatically on every trace, turning your business and safety requirements into quantifiable, trackable scores.

## When to use custom Scorers

Custom Scorers are the right tool when you need to check:

* **Domain-specific quality** — output structure, required sections, or business-specific language rules
* **Output format validation** — confirm the agent returns valid JSON, a specific schema, or a parseable date
* **Business rule compliance** — block responses that mention restricted topics, competitor names, or regulated terminology
* **Contextual safety** — toxicity or bias checks calibrated to your specific user base and content policy

## Create a Scorer

<Steps>
  <Step title="Open the Scorers view">
    In the [Trident dashboard](https://app.usetrident.dev), navigate to **Scorers** in the left sidebar and click **New Scorer**.
  </Step>

  <Step title="Name and describe your Scorer">
    Enter a short name (for example, `no-system-prompt-leak`) and a description that explains what the Scorer checks. The description appears alongside scores in the Traces view.
  </Step>

  <Step title="Write your scorer function">
    Use the built-in JavaScript editor to write your `scorer` function. The function receives a `trace` object and must return a number between `0` and `1`. See the function signature and example below.
  </Step>

  <Step title="Test against sample traces">
    Click **Test** to run your Scorer against recent traces from your project. The test panel shows the raw score and any errors, so you can iterate before saving.
  </Step>

  <Step title="Save and activate">
    Click **Save**. The Scorer is active immediately and runs on every new trace ingested into the project.
  </Step>
</Steps>

## Scorer function reference

Your scorer function receives a single `trace` argument and must return a score from `0` to `1`:

* `1.0` — full pass
* `0.0` — full fail (creates a Finding with source `SCORER`)
* Values between `0` and `1` — partial score, flagged if below `0.5`

```javascript scorer.js theme={null}
// scorer(trace) → number between 0 (fail) and 1 (pass)
function scorer(trace) {
  const lastMessage = trace.messages[trace.messages.length - 1];

  // Guard: no assistant message means something went wrong
  if (!lastMessage || lastMessage.role !== 'assistant') return 0;

  // Example: ensure the agent never reveals system prompt contents
  if (lastMessage.content.includes('system prompt')) return 0;

  // Example: ensure responses meet a minimum length for quality
  if (lastMessage.content.trim().length < 20) return 0.5;

  return 1;
}
```

### Available `trace` fields

| Field        | Type     | Description                                                            |
| ------------ | -------- | ---------------------------------------------------------------------- |
| `messages`   | `array`  | Ordered array of `{ role, content }` objects for the full conversation |
| `agentId`    | `string` | The agent identifier that produced this trace                          |
| `model`      | `string` | The model name used (for example, `gpt-4o`, `claude-3-5-sonnet`)       |
| `latencyMs`  | `number` | End-to-end response latency in milliseconds                            |
| `tokenCount` | `object` | `{ prompt, completion, total }` token counts                           |
| `toolCalls`  | `array`  | List of tool/function calls made during the trace                      |
| `metadata`   | `object` | Any custom metadata your SDK attached to the trace                     |

## Score results in the dashboard

After a Scorer runs, its result appears on each trace in the **Traces** view:

* A **pass badge** (score ≥ 0.5) in green
* A **fail badge** (score \< 0.5) in red, with the numeric score
* Scores of exactly `0` automatically create a **Finding** with source `SCORER`, severity determined by the Scorer's configured severity level

You can filter the Traces view by Scorer name and score range to audit specific patterns across your agent's history.

<Note>
  Scorers run in a sandboxed Node.js VM with no network access, no filesystem access, and a hard execution limit of 200ms. If your function throws an error or exceeds the time limit, the trace receives a score of `null` and a warning appears in the Scorer's activity log.
</Note>