ServiceTitan MCP

crm_leads_notes_list

Read-onlyIdempotent

Retrieve paginated notes for a known lead, filtered by created or modified timestamps to find relevant updates quickly.

Instructions

List one page of notes attached to a known lead, optionally filtered by created or modified timestamps. Requires the lead ID.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Lead ID
`page`	No	Page number (starts at 1)
`pageSize`	No	Records per page (default 50)
`includeTotal`	No	Include total count in response
`createdBefore`	No
`modifiedBefore`	No
`createdOnOrAfter`	No
`modifiedOnOrAfter`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv3.0.0Sep 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {},
+  "type": "object"
+}

First observedv2.5.1Apr 18, 2026

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the description does not need to restate safety. It does add useful behavioral detail beyond annotations: the tool returns only 'one page' of notes and supports optional timestamp filtering. However, it does not describe ordering, pagination behavior beyond the page concept, or any response characteristics, though an output schema exists.

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

Conciseness5/5

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

The description is a single efficient sentence that front-loads the core action and resource, then adds the filtering capability and the required lead ID. There is no repetition of schema details or annotations, and every phrase earns its place.

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

Completeness4/5

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

For a paginated, read-only list tool with an output schema and a required lead ID, the description covers the essential operational facts: it returns one page, it can filter by timestamps, and the lead ID is required. It does not mention how to navigate all pages or what happens if the lead ID is invalid, but those are secondary given the schema and annotations.

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 description coverage is 50%, with page, pageSize, includeTotal, and id already described in the schema. The description adds high-level meaning for the four timestamp parameters by saying results are 'optionally filtered by created or modified timestamps,' but it does not clarify the distinctions between the before/after parameters or their boundary 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?

The description starts with a specific verb and resource: 'List one page of notes attached to a known lead.' It clearly identifies both the entity type (lead) and the payload type (notes), and the 'one page' phrasing distinguishes it from tools that retrieve full note histories or lead records themselves. The requirement of a lead ID further pins down its scope.

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?

The description gives clear context for when to use the tool: when you already have a lead ID and need notes attached to that lead. It does not explicitly name alternatives such as crm_customers_notes_list or dispatch_jobs_notes_list, but the resource-specific wording makes the intended use obvious enough.

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

Deploy Server