Connect your AI client to Kepler CRM, a recruitment CRM. Search candidates and CRM records, read activity history, manage tasks and notes, and update recruiting pipelines with the permissions granted to your connection. Hosted Streamable HTTP endpoint with OAuth sign-in; each connection is bound to one Kepler workspace and respects the user's permissions. Requires a Kepler account with MCP enabled.
Scored across 13 tools
Each tool has a clearly distinct purpose, and the descriptions proactively cross-reference alternatives (open_kepler_desk vs get_work_queue, search_candidates vs list_records vs search_records, get_activity vs search_activities), telling the agent exactly when to prefer each. The only near-overlap is get_work_queue vs open_kepler_desk, but that boundary is spelled out explicitly.
All names follow a clean snake_case verb_noun pattern (aggregate_records, get_record, list_records, search_candidates, show_candidate_shortlist). Verbs vary appropriately by action while the structure stays fully predictable.
13 tools is well within the ideal 3-15 range for a CRM surface. Each tool earns its place by covering a distinct read/search/aggregate or UI-presentation concern without redundancy.
Read, search, and aggregation coverage is strong, but the descriptions repeatedly reference write tools (update_record, update_note, update_application_stage) that are not actually in the exposed set, and there is no create/update/delete tool at all. This leaves notable lifecycle gaps for a CRM domain despite good read coverage.
Computes counts, sums, averages, minimums, or maximums over one record type, optionally grouped by a field or a date bucket, with the same filters as list_records. Use for "how many", "per stage", "average fee", "placements per month". Returns exact figures from the database, never estimates. Placement consultant attribution groups count each placement by its percentage share; fee metrics are net of credited rebates and money is returned per currency without conversion. For pipeline questions aggregate applications, not candidates.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | ||
| filters | Yes | ||
| group_by | Yes | ||
| date_bucket | Yes | ||
| metric_field | Yes | ||
| resource_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description discloses meaningful behavioral nuances: returns exact figures, never estimates; placement consultant attribution groups by percentage share; fee metrics are net of credited rebates; and money is returned per currency without conversion. These are non-obvious traits the agent could not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all dense with useful information and no filler. The core computation is front-loaded, followed by usage examples, then caveats and domain rules. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 required parameters and an output schema, so return-value details are not needed in the description. The description covers the essential decision factors: what metrics are available, how grouping works, filter reuse, exactness guarantees, attribution semantics, fee adjustments, currency behavior, and a pipeline-specific rule. This is complete for an agent deciding whether and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It maps well to most parameters: 'one record type' implies resource_type, 'grouped by a field or a date bucket' covers group_by and date_bucket, the metric list covers metric, and 'same filters as list_records' covers filters. However, metric_field is only indirectly implied via 'average fee' and 'fee metrics', so the agent still has some ambiguity about which parameter denotes the numeric field being aggregated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Computes'), a precise resource ('one record type'), and the exact operations ('counts, sums, averages, minimums, or maximums'). It goes beyond the tool name by explaining optional grouping and filtering, and the examples ('how many', 'per stage', 'average fee') make the tool's role unmistakable relative to list_records and search_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('Use for "how many", "per stage", "average fee", "placements per month"') and even provides a domain rule ('For pipeline questions aggregate applications, not candidates'). It also references list_records for filter compatibility, giving the agent clear context for when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the fields of a record type: standard fields, this workspace's custom fields with their slugs, types, allowed options, and whether each can be written, plus the workspace pipeline stages for applications. Call it before filtering on or writing any workspace-specific attribute, and before update_application_stage. Pass writable_only to see only what update_record accepts. No data rows are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_type | Yes | ||
| writable_only | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: it returns no data rows, exposes workspace-specific fields, and includes pipeline stages only for applications. Minor omissions like auth requirements or rate limits are acceptable given the strong annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense, front-loaded sentences cover purpose, scope, usage timing, filtering, and return behavior without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, output schema, and clear usage guidance, the description covers what an agent needs to invoke the tool correctly. The only small gap is that writable_only is marked required in the schema while the description reads as if it may be optional, but this does not seriously impair correctness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'writable_only' as filtering to what update_record accepts and refers to 'record type' for resource_type, but it does not explicitly map resource_type to the parameter or clarify that writable_only is required. It adds some meaning but does not fully cover both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('fields of a record type'), and enumerates exactly what is included: standard fields, custom fields with slugs/types/options/writability, and pipeline stages. This clearly distinguishes it from sibling data-returning tools like list_records or get_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to call it: 'before filtering on or writing any workspace-specific attribute' and 'before update_application_stage.' It does not explicitly name alternatives to avoid, but the usage context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads one note, call, meeting, email, or other activity in full by id, including body text (HTML notes are returned as plain text with the HTML alongside), links, and version. Use after search_activities when the snippet is not enough, and before update_note.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | UUID |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral detail beyond annotations, such as how HTML notes are returned ('as plain text with the HTML alongside'), which is not inferable from annotations or schema. This is exactly the kind of context that helps an agent understand output handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The main action and scope are front-loaded, and the usage guidance is packed into a single, actionable sentence. Every word earns its place, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one required parameter, an output schema exists, and annotations cover safety. The description supplies the essential context: when to use it, what it returns (body, links, version), and the HTML handling quirk. Nothing an agent needs to call it correctly is missing, so it is fully complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the single parameter 'id' is merely 'UUID' — a format, not a semantic meaning. The description adds the phrase 'by id' and clarifies that it is the activity identifier, which provides semantic value beyond the schema. Since schema coverage is 100% but the schema is semantically thin, the description meaningfully compensates, justifying a 4 rather than a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reads... in full by id'), the resource ('one note, call, meeting, email, or other activity'), and the scope ('including body text, links, and version'). It also distinguishes itself from siblings by explicitly positioning it after search_activities and before update_note, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'Use after search_activities when the snippet is not enough, and before update_note.' This provides clear context, alternatives, and sequencing, leaving no doubt about its place in a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns who you are acting as and the conventions this CRM expects: user id, workspace, role, today's date and timezone, the tools and scopes this connection may use, a short list of domain rules (how "my" resolves, what "candidates in the pipeline" means, how periods are interpreted), and the workspace's own definitions of what its objects mean. Call it once at the start of a conversation and before resolving any relative date or ownership phrase.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it lists the exact content of the response (role, timezone, permitted tools/scopes, domain rules) and instructs a one-time call pattern, which helps the agent understand side-effect-free initialization behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the core purpose before enumerating contents and usage. It is slightly long but every clause adds meaningful detail about what the agent gets and when to call it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with a rich output schema, the description fully covers what is returned, why it matters, and the recommended call timing. No critical information an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema carries no burden. Per the baseline for parameterless tools, a 4 is appropriate; the description need not elaborate on inputs, and it correctly focuses on return-value semantics instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Returns') and a precise resource: the acting user identity plus CRM conventions. It clearly distinguishes itself from sibling tools like get_record or search_candidates by focusing on identity, workspace, and domain rules rather than business-object data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: 'Call it once at the start of a conversation and before resolving any relative date or ownership phrase.' This gives the agent an unambiguous trigger condition, and no alternative is needed since siblings cover different purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the stored results of the most recent matching run for a job: ranked candidates with scores, per-criterion verdicts, evidence, and missing must-haves. It never starts or refreshes a run and has no AI cost. Use it for "why is she ranked first", "who fails a mandatory criterion", or to intersect matches with another attribute. If no run exists it says so; ask the user to run matching in Kepler.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | Default 25, max 50. | |
| state | Yes | ||
| cursor | Yes | next_cursor from the previous page. | |
| job_id | Yes | UUID | |
| criterion_status | Yes | ||
| mandatory_verdict | Yes | ||
| detail_candidate_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavioral context: it never starts a run, incurs no AI cost, and clearly reports an absent matching run instead of silently returning empty results. This helps the agent set user expectations accurately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no filler. The core action is front-loaded, followed by concrete use cases and a failure-mode caveat. Every sentence adds decision-relevant value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations are rich, the description covers what an agent needs to decide whether to call the tool and what to expect. It provides semantics, exclusions, use-case examples, and the no-run behavior. The only gap is the lack of explicit guidance for state and detail_candidate_ids, but their enum/format definitions mitigate this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43% (job_id, limit, cursor are described), and the description only partially compensates. It maps output concepts like 'per-criterion verdicts' and 'missing must-haves' to criterion_status and mandatory_verdict, but leaves state and detail_candidate_ids semantically implicit. The parameter names and enums help, but the description does not fully clarify these two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Reads the stored results of the most recent matching run for a job'. It enumerates the returned content—ranked candidates with scores, per-criterion verdicts, evidence, and missing must-haves—making the tool's purpose unmistakable and distinct from sibling search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool is appropriate: reading existing results, exploring 'why is she ranked first', finding candidates who fail a mandatory criterion, or intersecting matches with another attribute. It also gives a clear exclusion—'It never starts or refreshes a run and has no AI cost'—and tells the agent what to do if no run exists: ask the user to run matching in Kepler.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads one record in full by exact id: all standard fields, custom fields by slug, version, and the few related rows needed next (a candidate's applications with stage and status, a job's company and open application counts, a list's member ids). Requires an id from a search or list result. Use this before any update so you have expected_version. Never guess an id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | UUID | |
| record_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and idempotent, and the description adds meaningful behavioral context: the return includes standard fields, custom fields by slug, version, and selected related rows. It also discloses the version-related requirement for safe updates, which is valuable beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but well organized: purpose first, then output details, then usage guidance. Every sentence earns its place, with no filler or repetition of schema data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with an output schema and read-only annotations, the description covers all necessary operational context: how to obtain a valid id, what data to expect, and how to use the result for updates. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description compensates by explaining the id must come from a search or list result and must not be guessed. It also illustrates record_type impact through examples like candidate applications and job company counts, though it does not explicitly define every enum value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Reads one record in full by exact id') and enumerates what 'full' includes, distinguishing it from list/search tools. It also gives concrete record-type examples, so an agent can immediately understand the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: requires an id from a search or list result, use before updates to get expected_version, and never guess an id. It does not explicitly name sibling alternatives, but the prerequisite flow is implied through 'Requires an id from a search or list result.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the user's prioritised operational picture in one call: overdue and due-today tasks, stalled submissions, jobs with no recent activity, interviews missing feedback, guarantees expiring, and today's agenda, each with counts and ages. Use for "what needs my attention", "what should I do today", "what am I waiting on". Do not rebuild this from separate searches. Figures in one group apply only to that group.
| Name | Required | Description | Default |
|---|---|---|---|
| days | Yes | Window in days, both directions. Default 7. | |
| scope | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and idempotentHint already trueched, the description adds extra behavioral context by noting the single-call naturechers and by warning that 'figures in one group apply only to that group'. It also states the result includes counts and ages. This meaningfully supplements the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose and content appear in the first sentence, followed by direct use-case guidanceeto, an explicit exclusion of separate searches, and a necessary caveat. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is conceptually an aggregation of many result groups, and the description lists those groups clearly. The output schema covers return structure, and annotations cover safety, so the missing clarification of the 'scope' parameter is the main gap. Given the available schema and annotation context, the description is otherwise sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description says nothing about the two parameters. The schema documents 'days' (window and default), but 'scope' has only an enum and its semantics are not explained. With schema description coverage at 50%, the description does not compensate for the undocumented param, and 'user's' could even mislead about the effect of scope=workspace.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') with a clear resource ('the user's prioritised operational picture in one call'), then enumerates the exact categories included. It is self-evidently distinct from the sibling search/record tools, which do one type of lookup rather than this multi-group aggregate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use-case phrases ('what needs my attention', 'what should I do today', 'what am I waiting on') and explicitly advises against rebuilding the same picture from separate searches. It does not name specific alternative tools or state when they should be used instead, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns exact rows of one record type by structured filters and sorts, with a total count. Use for browse or comparison questions with concrete criteria ("open contract jobs in Sydney", "candidates whose notice period is one month"). Field ids and custom-field slugs come from describe_fields; filter values must be ISO dates or option slugs. For fuzzy or CV-content criteria use search_candidates. Pages of 50; follow next_cursor for more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | Default 25, max 50. | |
| sorts | Yes | ||
| cursor | Yes | next_cursor from the previous page. | |
| fields | Yes | Restrict returned columns. | |
| filters | Yes | ||
| resource_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns exact rows (not fuzzy matches), includes a total count, pages of 50, and requires following next_cursor for more. It also discloses that filter values must be ISO dates or option slugs, which is a behavioral constraint not visible in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core behavior is in the first sentence, usage examples follow, and the alternative tool is named. Every sentence earns its place—no filler, no repetition of schema details. It is appropriately sized for a tool with 6 parameters and rich schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so return values are documented elsewhere), the description covers what an agent needs to call the tool correctly: what it returns, how to filter/sort, where to get field identifiers, pagination behavior, and when to use a sibling instead. The only minor gap is not explaining the total count's position in the response, but the output schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the schema documents some parameters (limit, cursor, fields, filters partially) but not all. The description compensates by explaining that field ids and custom-field slugs come from describe_fields, that filter values must be ISO dates or option slugs, and that pages are 50 with next_cursor for pagination. It adds meaning beyond the raw schema, though it doesn't enumerate every parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Returns exact rows'), a resource ('one record type'), and the key capabilities (structured filters, sorts, total count). It also distinguishes itself from search_candidates by explicitly saying it is for structured criteria, not fuzzy/CV-content. This clearly differentiates it from siblings like search_records and search_candidates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance with concrete examples ('open contract jobs in Sydney', 'candidates whose notice period is one month') and explicitly names the alternative for fuzzy/CV-content criteria ('use search_candidates'). It also tells the agent where to get field ids and custom-field slugs (describe_fields), which is essential for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opens the user's Kepler desk: their work queue (overdue and due-today tasks, submissions awaiting feedback, stale jobs, interviews missing feedback, today's agenda) grouped by section, where tasks can be completed and records opened in Kepler. Use this when the user wants to see or work through their queue ("open my desk", "show my day"). For a text answer about what needs attention, use get_work_queue instead. Both arguments are optional.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window in days, both directions. Default 7. | |
| scope | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds useful context beyond that: the content is grouped by section, and it hints the returned surface is interactive (tasks completed, records opened in Kepler) rather than a plain list. It does not flag the read-only nature explicitly, which would have resolved any ambiguity about the 'tasks can be completed' phrasing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and its contents, then routes to the alternative, then notes argument optionality. The long parenthetical enumeration is dense but earns its place by telling the agent what the desk actually returns. No filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not required in the description. Combined with annotations covering the safety profile, the description is nearly complete for an opening/display tool; the only real gap is that 'scope' semantics (me vs workspace) are unexplained anywhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'days' carries a schema description with default and bounds, but 'scope' has only a bare me/workspace enum with no explanation of what workspace scope returns or when to choose it. The description adds only 'Both arguments are optional', which restates what the schema already shows (zero required params) and does not compensate for the undocumented scope semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (opens the user's Kepler desk) and enumerates exactly what that surface contains: overdue/due-today tasks, submissions awaiting feedback, stale jobs, interviews missing feedback, today's agenda, grouped by section. This clearly distinguishes it from siblings like get_work_queue and get_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete trigger phrasing ("open my desk", "show my day") and explicitly names the alternative for a different need: "For a text answer about what needs attention, use get_work_queue instead." When-to-use and when-to-use-something-else are both stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches history: notes, comments, calls, meetings and their summaries, emails, messages, and timeline updates, optionally scoped to one record, actor, type, or date range. Use for "what did we discuss", "when did we last contact", "who said X". Mode exact finds verbatim wording; hybrid (default) ranks by meaning. Each item carries the activity id, type, date, actor, linked records, and a snippet. Summaries are excerpts; read get_activity for the full body.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| limit | Yes | ||
| query | Yes | ||
| types | Yes | ||
| date_to | Yes | ||
| actor_id | Yes | ||
| date_from | Yes | ||
| record_id | Yes | ||
| record_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: mode semantics (exact = verbatim, hybrid = ranked by meaning) and the undocumented fact that hybrid is the DEFAULT, the fields returned per item, and the caveat that summaries are excerpts requiring get_activity for the full body.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with what is searched, then intents, then ranking behavior, then return shape – every sentence earns its place. The enumeration in sentence one is dense but load-bearing, so structure is strong without being padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter tool with zero schema descriptions, the description supplies the essential search semantics and even explains return shape despite an output schema existing. It is complete enough to call correctly, though it leaves limit/pagination bounds and the all-required-quirks of the schema undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It meaningfully covers the scoping params (record, actor, type, date range) and the mode enum semantics, but omits the limit parameter and its max of 25, the maxLength on query, and does not clarify that all nine parameters are required or how nulls act as defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Searches history') and enumerates exactly what is searched (notes, comments, calls, meetings, emails, messages, timeline updates) plus the scoping dimensions. It also names the related sibling get_activity for full bodies, so the agent can distinguish this search tool from the read-one-activity tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use intents ('what did we discuss', 'when did we last contact', 'who said X') and routes to the alternative get_activity when a full body is needed. It stops short of explicit when-not-to-use guidance, e.g. how it differs from search_records or search_candidates, so it does not reach a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds candidates by meaning across profile, CV text, recruiter notes, and call or meeting summaries. Use for skills, experience, background, or things a candidate said; combine with filters for status, location, owner, or custom fields. Put non-negotiable terms (a company, certification, tool) in must_include to hard-exclude candidates whose corpus lacks them. Returns ranked rows with a snippet showing why each matched. Use list_records instead for exact structured lookups. Bounded to 50 per call; total_count says how many matched.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| limit | Yes | Default 25, max 50. | |
| query | Yes | Words you expect in the CV, notes or summaries, not a description of the search. | |
| cursor | Yes | next_cursor from the previous page. | |
| filters | Yes | ||
| must_include | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful beyond-annotation behavior: ranked results with a matching snippet, a hard-exclude rule for must_include, the 50-per-call bound, and the total_count field. This gives the agent a clear picture of pagination and result semantics without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 70 words, front-loaded with the core purpose, and each sentence delivers distinct value: what it searches, when to use it, the must_include behavior, result format, exact-lookup alternative, and pagination cap. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the filters and the existence of an output schema, the description covers most operational needs: search scope, filter combination, must_include semantics, result ranking and snippet, the 50-row bound, and the pagination indicator. The only notable missing piece is the mode parameter semantics, but the enum values are somewhat self-explanatory and the output schema fills return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, so the description needs to compensate. It does add value for must_include ('hard-exclude candidates whose corpus lacks them') and gives example filter fields (status, location, owner, custom fields). However, it never explains the mode parameter (hybrid/semantic/exact), which is required and undocumented in the schema, leaving an important semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Finds candidates by meaning across profile, CV text, recruiter notes, and call or meeting summaries.' This clearly distinguishes the tool from exact-lookup siblings by emphasizing semantic/full-text search over candidate-related texts. It also names the sibling it is not ('Use list_records instead for exact structured lookups'), so an agent can immediately tell which tool fits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('Use for skills, experience, background, or things a candidate said') and how to constrain it with filters. It provides a direct alternative with the condition for choosing it ('Use list_records instead for exact structured lookups'), giving the agent actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cross-type lookup by name, title, email, domain, or free text over jobs, companies, contacts, applications, placements, tasks, and saved lists. Use it to resolve "the Acme role" or "Priya's application" to exact ids before reading or writing. For candidates use search_candidates. Returns up to 25 per call with type, id, label, and a one-line context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| query | Yes | ||
| resource_types | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds concrete behavioral details—returns up to 25 results with type, id, label, and a one-line context—which helps the agent set expectations. It doesn't contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences, front-loaded with purpose and usage. The first sentence defines scope and fields; the second adds routing, limit, and return format. Every clause earns its place—no filler, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 0% schema coverage, the description fully covers the three parameters, the return shape, the alternative tool, and the typical use case. An agent can decide when to call, what arguments to pass, and what to expect in the response. The presence of an output schema also covers return structure, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It explains the query semantics ('name, title, email, domain, or free text') and the resource scope (the enum list), and mentions the limit cap ('up to 25'). It doesn't explicitly map each parameter name (query, resource_types, limit) but the meaning is clear enough to call correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource combination: 'Cross-type lookup' over explicitly listed resource types (jobs, companies, contacts, applications, placements, tasks, saved lists). It immediately distinguishes itself from search_candidates, making the purpose unambiguous even without reading the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool ('resolve ... to exact ids before reading or writing') and when not to ('For candidates use search_candidates'). This gives the agent actionable routing guidance and names the specific sibling, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows 1-12 candidates the user is considering as compact cards: name, current title and employer, location, a one-line highlight, owner, and (with job_id) their stage on that job. From the card the user can add a candidate to the job or open them in Kepler. Use this when presenting a shortlist after search_candidates, get_job_matches or list_records found the people. Do not use it to search, and do not repeat the card's contents in prose. Requires exact candidate ids from a read in this conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Card heading, e.g. "Data engineers for Meridian". | |
| job_id | No | The job being shortlisted for; shows each stage and enables "Add to job". | |
| candidate_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior the annotations cannot: the output is a rendered card set with interactive affordances (add to job, open in Kepler), and it constrains inputs to ids obtained from a prior read in the same conversation. It stops short of describing pagination or failure modes, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what renders, then routing guidance, then the hard prerequisite. Each sentence carries distinct information and none is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return shape need not be re-explained, yet the description still tells the agent what visually appears on the cards. Combined with annotation-covered safety and the stated id-provenance constraint, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description adds the item bound ('1-12 candidates', matching minItems/maxItems) and the fact that job_id toggles stage display and the 'Add to job' action, plus the provenance requirement for candidate_ids. The title parameter's purpose (card heading) is only covered by the schema, which keeps this from being a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Shows 1-12 candidates... as compact cards') and enumerates exactly what each card contains, including the job_id-dependent stage field. An agent can distinguish it from search_candidates, get_job_matches and list_records without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('after search_candidates, get_job_matches or list_records found the people'), explicit when-not ('Do not use it to search'), plus a prerequisite ('Requires exact candidate ids from a read in this conversation') and a presentation rule ('do not repeat the card's contents in prose'). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
open_kepler_desksearch_activities1 field changedInput schema / properties / types / anyOfPrevious value: -[
- {
- "items": {
- "enum": [
- "note",
- "comment",
- "call",
- "meeting",
- "message",
- "email",
- "update",
- "task_event"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "enum": [
+ "note",
+ "comment",
+ "team_comment",
+ "call",
+ "meeting",
+ "message",
+ "email",
+ "update",
+ "task_event"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]show_candidate_shortlistaggregate_records1 field changedOutput schema / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "groups": {
- "anyOf": [
- {
- "items": {
- "additionalProperties": false,
- "properties": {
- "count": {
- "maximum": 9007199254740991,
- "minimum": -9007199254740991,
- "type": "integer"
- },
- "key": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "label": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "value": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ]
- }
- },
- "required": [
- "key",
- "label",
- "value",
- "count"
- ],
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ]
- },
- "metric": {
- "enum": [
- "count",
- "sum",
- "avg",
- "min",
- "max"
- ],
- "type": "string"
- },
- "metric_field": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "resource_type": {
- "enum": [
- "candidate",
- "contact",
- "company",
- "job",
- "application",
- "placement",
- "task"
- ],
- "type": "string"
- },
- "rows_with_value": {
- "anyOf": [
- {
- "maximum": 9007199254740991,
- "minimum": -9007199254740991,
- "type": "integer"
- },
- {
- "type": "null"
- }
- ]
- },
- "total": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "type": "null"
- }
- ]
- },
- "truncated": {
- "type": "boolean"
- }
- },
- "required": [
- "resource_type",
- "metric",
- "metric_field",
- "total",
- "rows_with_value",
- "groups",
- "truncated"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "error": {
- "additionalProperties": false,
- "properties": {
- "details": {
- "additionalProperties": {},
- "propertyNames": {
- "type": "string"
- },
- "type": "object"
- },
- "message": {
- "type": "string"
- },
- "request_id": {
- "type": "string"
- },
- "type": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "message",
- "request_id"
- ],
- "type": "object"
- }
- },
- "required": [
- "error"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "groups": {
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "count": {
+ "type": "number"
+ },
+ "key": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "label": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "value": {
+ "anyOf": [
+ {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ }
+ ]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "key",
+ "label",
+ "value",
+ "count"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "metric": {
+ "enum": [
+ "count",
+ "sum",
+ "avg",
+ "min",
+ "max"
+ ],
+ "type": "string"
+ },
+ "metric_field": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "resource_type": {
+ "enum": [
+ "candidate",
+ "contact",
+ "company",
+ "job",
+ "application",
+ "placement",
+ "task"
+ ],
+ "type": "string"
+ },
+ "rows_with_value": {
+ "anyOf": [
+ {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "total": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "resource_type",
+ "metric",
+ "metric_field",
+ "total",
+ "rows_with_value",
+ "groups",
+ "truncated"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "error": {
+ "additionalProperties": false,
+ "properties": {
+ "details": {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "message": {
+ "type": "string"
+ },
+ "request_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "message",
+ "request_id"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "type": "object"
+ }
+]aggregate_recordsdescribe_fieldsget_activityget_current_userget_job_matchesget_recordget_work_queuelist_recordssearch_activitiessearch_candidatessearch_records
Add one secure layer between your agents and this server.