Remote MCP server for GateKeeperAI, a CRM with an AI phone receptionist for service businesses. Lets ChatGPT, Claude and Cursor search leads, read call transcripts and notes, update pipeline stages and log activity for your business. OAuth 2.0 with read and write scopes.
Scored across 37 tools
Most tools target distinct resources, but there is meaningful overlap between log_activity and log_outreach, and between create_contact and create_lead, which both can create or link a person. send_lead_sms and send_lead_email also overlap with log_outreach because sending and recording outreach are split across tools. The long descriptions help, but the boundaries still require careful reading.
Tool names are consistently snake_case and overwhelmingly follow a verb_noun pattern, such as create_contact, list_tasks, and move_deal_stage. The main deviation is list_opportunities for deals, while the rest of the deal-related surface uses deal (create_deal, move_deal_stage). That is a minor but noticeable noun inconsistency.
The server exposes 37 tools, which is heavy for a single MCP surface even for a CRM with contacts, leads, deals, pipelines, tasks, calls, mailboxes, and Meta routing. The breadth is understandable, but the count exceeds the well-scoped range and increases tool-selection burden.
Contacts have full CRUD, tasks and pipelines are well covered, and core lead-to-deal workflows are present. However, leads lack update/delete beyond set_lead_status, and deals lack get/update/delete beyond create, list, and stage movement. Those are notable gaps for a CRM surface even if some are workaroundable via listings and related contact tools.
Add a person to the CRM who has not called, chatted or filled in a form. Needs at least one of name, email or phone. IF THE EMAIL OR PHONE ALREADY BELONGS TO A CONTACT, NO NEW CONTACT IS CREATED: the existing one is returned with created=false. Whenever created is false, any identifier the existing contact was missing is filled in from what you sent, and so is a first or last name whose stored value is null; a name they already have is never overwritten, and their lifecycle stage is never touched. created is the ONLY field that tells you whether a person was added. matchedOn names the identifier this tool matched on when it can attribute the match, and is null otherwise — it is a hint, never the answer to "did this already exist". Worked examples: a new person gives created=true, matchedOn=null. An email that already belongs to someone gives created=false, matchedOn=email. Never re-run this to force a second contact.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email address | ||
| phone | No | Phone number, any format | |
| last_name | No | Last name | |
| first_name | No | First name | |
| lifecycle_stage | No | Lifecycle stage; defaults to lead |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover non-destructive write/openWorld, but the description discloses the entire upsert contract: existing contact returned with created=false, missing identifiers backfilled, non-null names never overwritten, lifecycle stage untouched. It also explains that created is the only authoritative signal and matchedOn is merely a hint, which prevents a real class of agent errors.
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 purpose, then the match semantics, then worked examples; nearly every sentence carries non-obvious information. The all-caps and the two worked examples are slightly heavy but they disambiguate a genuinely tricky return contract.
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?
No output schema exists, so the description must explain the return payload itself — and it does, defining created and matchedOn and their interaction. Combined with the merge rules, an agent has everything needed to interpret results and avoid duplicate creation.
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 100%, so the baseline is 3, but the description adds a constraint not encoded in the schema: required is empty yet 'at least one of name, email or phone' must be supplied. It also clarifies that the stored lifecycle stage is never overwritten on match.
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 ('Add a person to the CRM') and narrows scope with 'who has not called, chatted or filled in a form', which implicitly separates it from create_lead for inbound leads. It never names that sibling explicitly, so differentiation requires a small inference.
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 clear when-to-use conditions and an explicit prohibition ('Never re-run this to force a second contact'), plus the minimum-identifier rule. It stops short of naming an alternative tool for the excluded channels (e.g. create_lead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a deal, optionally linked to a contact. It starts in the FIRST stage of the pipeline and move_deal_stage moves it on from there; you cannot pick a starting stage, because a stage only means anything relative to its own pipeline. By default the deal goes into the account default pipeline. Pass pipeline_id to put it in a different one: from THIS tool set that is the only way a non-default pipeline receives a deal, so a pipeline created by create_pipeline stays an empty board until you do. (A website form can also be configured to file its submissions into a chosen pipeline, which is outside these tools.) Get pipeline ids from list_pipeline_stages, whose rows carry pipeline_id, pipeline_name and pipeline_is_default. The result reports the pipeline_id the deal actually landed in.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | What the deal is called | |
| amount | No | Deal value; omit if unknown | |
| contact_id | No | Link the deal to this contact | |
| pipeline_id | No | Put the deal in this pipeline instead of the default one; omit for the default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a non-read-only, non-destructive, closed-world mutation. The description adds meaningful behavior beyond that: the deal always starts in the FIRST stage, the starting stage cannot be chosen, and the result reports the actual pipeline_id. It does not cover permissions or error cases, but adds substantial operational context.
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 front-loaded with the core action and optional linkage, then layers in pipeline behavior. It is dense but each clause supports correct invocation. The parenthetical about website forms is slightly extraneous but serves to delimit scope, so the length is justified overall.
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 four-parameter mutation tool with no output schema, the description covers the critical behavioral quirks: default pipeline, immutability of starting stage, and the result's pipeline_id report. It omits error handling and permission requirements, but for this tool's complexity the description is nearly complete.
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 100%, so the schema already documents all four parameters. The description still adds semantic depth for pipeline_id—explaining its default behavior, its exclusivity within this toolset, and how to obtain valid IDs via list_pipeline_stages—which goes beyond the schema snippet.
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 first sentence states a specific verb and resource ('Create a deal') and immediately notes the optional contact linkage. It clearly distinguishes the tool from siblings like create_pipeline and move_deal_stage by explaining its role in the pipeline lifecycle.
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 pipeline_id versus relying on the default, names the alternative (move_deal_stage) for advancing stages, and directs the agent to list_pipeline_stages for IDs. It also clarifies that a pipeline created by create_pipeline stays empty until this tool is used with its ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an enquiry that arrived off-platform: a walk-in, a referral, a card taken at an event. Needs at least one of name, email or phone. The source is always "manual" and cannot be set — do not use this to backfill a lead that really came from a call, a form or an ad, because source drives attribution and reporting. The matching contact is created or linked automatically IN ALMOST EVERY CASE, and the result tells you when it was not. contact_linked false means the lead IS saved but no contact was linked to it, so it is on nobody's timeline and is invisible to contact search. THERE IS NO TOOL THAT CAN ATTACH IT AFTERWARDS, so never tell the user it can be fixed. Do not retry create_lead either, that leaves a duplicate lead behind even when it succeeds. Report it plainly. To preserve the enquiry itself, call create_contact for the same person and then log_activity on that contact with what they wanted: that puts the enquiry on their timeline, which the orphaned lead never will. create_contact alone does not rescue this lead. No new-lead alert is sent. The message you send is recorded as your team's internal note about this person, never as something they wrote: the AI reply draft is told not to quote it, and get_lead, list_leads and get_contact all return it with its authorship attached. It is still your own note, so write it for your team and assume a colleague will read it on the lead's record.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The person name | |
| No | Email address | ||
| phone | No | Phone number, any format | |
| message | No | A short note for your own team on what they want. This is stored and surfaced as YOUR note about the person, never as their own words, so it is never quoted back to them: write it plainly rather than trying to phrase it as a quote. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say this is a non-read-only, non-destructive write; the description supplies the real behavioral payload: the contact is auto-created or linked 'IN ALMOST EVERY CASE', contact_linked false means the lead is saved but orphaned and no tool can attach it later, retrying produces duplicates even on success, and no new-lead alert fires. It also discloses that the message is stored as the team's internal note and is surfaced with authorship attached in get_lead, list_leads and get_contact — none of which is derivable from the annotations or schema.
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 critical scope constraint is front-loaded, but the orphaned-lead warning is restated three times ('contact_linked false means...', 'THERE IS NO TOOL THAT CAN ATTACH IT AFTERWARDS', 'create_contact alone does not rescue this lead') and the message-authorship point is also repeated. The emphasis-by-capitals plus repetition inflates length beyond what the content requires.
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?
With no output schema, the description carries the burden of the return value and does so by explaining contact_linked false in concrete terms (lead saved, no timeline, invisible to contact search). Combined with the mandatory source behavior, duplicate-on-retry warning and note-authorship disclosure, an agent has everything needed to call this correctly and to report the outcome honestly.
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 100%, so the schema already documents all four fields and the message semantics. The description still adds a cross-field constraint not present in the schema — 'Needs at least one of name, email or phone' — while the schema declares zero required parameters, which is genuinely load-bearing information for an agent.
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 and immediately narrows scope: 'Record an enquiry that arrived off-platform: a walk-in, a referral, a card taken at an event.' It also names the forbidden use case (backfilling leads that 'really came from a call, a form or an ad'), which cleanly separates it from form/call/ad ingestion paths and from create_contact.
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 (off-platform enquiry), explicit when-not (backfill from a call, form or ad) with the reason (source drives attribution and reporting), and an explicit alternative workflow when the lead is orphaned: create_contact then log_activity. It even rules out a tempting wrong fix ('create_contact alone does not rescue this lead').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a deal pipeline. To set one up the way the business actually works, pass stages: the OPEN stages in left-to-right order (1 to 15, e.g. ["Inquiry", "Consult booked", "Proposal sent"]), and optionally won_stage_name and lost_stage_name (default "Won" and "Lost", e.g. "Retained" and "Not hired"). The won and lost stages are always added at the end and drive lead outcomes and win reporting. Without stages it is seeded with the standard New, Qualified, Proposal, Won, Lost. Every stage name must be different, ignoring case. If the account has no default pipeline yet, this one becomes the default. Most accounts need only one pipeline: to change an existing one, use rename_pipeline_stage, create_pipeline_stage, delete_pipeline_stage and reorder_pipeline_stages instead of making a second. IF A PIPELINE WITH THAT NAME ALREADY EXISTS, ignoring case, NOTHING IS CREATED OR CHANGED: the existing one is returned with created=false, and created is the ONLY field that tells you which happened. Do not work around it by adding a number to the name. A new pipeline starts with no deals; pass its pipeline_id to create_deal, or make it the default with set_default_pipeline so new leads land in it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pipeline name, e.g. "Intake" or "Renewals" | |
| stages | No | The open stages in board order. Omit for the standard New, Qualified, Proposal | |
| won_stage_name | No | Name of the won stage (default "Won"). Only used with stages | |
| lost_stage_name | No | Name of the lost stage (default "Lost"). Only used with stages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the duplicate-name behavior (nothing is created, existing pipeline is returned with created=false, and that is the only distinguishing field), the case-insensitive uniqueness rule, the default-pipeline side effect, and that won/lost stages are appended at the end. These are exactly the non-obvious behaviors an agent must know before invoking.
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?
Purpose is front-loaded in the first sentence and the remaining sentences each carry distinct operational detail (stage ordering, defaults, duplicate handling, next steps). It is long for a four-parameter tool, and the capitalized duplicate-name warning plus the 'do not add a number to the name' admonition are slightly verbose, but no sentence is purely filler.
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 creation tool with no output schema and no annotations beyond safety hints, the description covers the seeded defaults, uniqueness constraint, idempotent-failure semantics, default-pipeline effect, and follow-up calls. An agent has everything needed to call it correctly and interpret the result, including the created flag.
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 100%, so the schema already documents parameter names, types, and bounds. The description still adds meaning the schema lacks: stages are in left-to-right board order with worked examples, won_stage_name/lost_stage_name are only honored when stages is passed, and names must be unique ignoring case. Minor gap: it does not restate the 1–15 item bound, but that is in the schema.
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 ('Create a deal pipeline') in the first phrase, and distinguishes itself from sibling stage-editing tools by naming rename_pipeline_stage, create_pipeline_stage, delete_pipeline_stage and reorder_pipeline_stages as the alternative for modifying an existing pipeline.
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?
Explicitly says most accounts need only one pipeline and directs the agent to the stage-editing siblings instead of creating a second one. It also prescribes the next step after creation (pass pipeline_id to create_deal or call set_default_pipeline), so when-to-use and what-to-do-next are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a stage to a pipeline. It is inserted before the Won and Lost stages so the pipeline still reads in order. Probability is a FRACTION between 0 and 1 (0.6 means 60 percent), matching the existing stages. Get pipeline_id from list_pipeline_stages, whose rows also carry pipeline_name and pipeline_is_default so you can tell one pipeline from another — to add a step to the pipeline new deals go into, pick the pipeline_id whose pipeline_is_default is true. An account with no pipeline yet has no stages to list and no pipeline_id to pass here: call create_pipeline to make one, or create_deal, which creates the default pipeline as a side effect. IF A STAGE WITH THAT NAME ALREADY EXISTS IN THAT PIPELINE, ignoring case, NO NEW ONE IS CREATED: the existing one is returned with created=false. Two columns with one heading cannot be told apart on the board. To change an existing stage use rename_pipeline_stage, delete_pipeline_stage or reorder_pipeline_stages.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stage name, e.g. "Contract sent" | |
| pipeline_id | Yes | The pipeline id, as returned by list_pipeline_stages | |
| probability | No | Win probability as a fraction from 0 to 1; defaults to 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only say non-read-only, non-destructive), the description discloses the insertion position, the dedupe rule (case-insensitive name match creates nothing and returns the existing stage with created=false), and that probability mirrors existing stages. The created=false return flag is behavior an agent cannot infer from structured fields.
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 action and its placement, then prerequisites, then edge cases — a logical order with no filler. It runs long and relies on em-dashes and parentheticals, but nearly every clause carries decision-relevant information.
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?
Covers the full call path: where the id comes from, the bootstrap case with no pipeline, the idempotent no-op case, and where to go to change a stage instead. With no output schema, it even gestures at the return (created=false), leaving nothing critical unstated.
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 100%, so the baseline is 3; the description earns more by explaining the probability convention in context ('matching the existing stages') and by framing the name parameter as a uniqueness key within a pipeline. It still doesn't add anything about the optionality or defaults of probability beyond the schema.
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 ('Add a stage to a pipeline') and immediately clarifies placement (inserted before Won/Lost so the board reads in order). It is unambiguously distinguished from siblings like create_pipeline, rename_pipeline_stage, and reorder_pipeline_stages, which are named later.
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?
Explicitly routes the agent: get pipeline_id from list_pipeline_stages, pick the row with pipeline_is_default=true for the pipeline new deals go into, and use create_pipeline or create_deal when no pipeline exists yet. It also names the correct alternatives for modifying an existing stage rather than adding one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a task, optionally linked to a contact and with a due date. If this account has a connected Google Tasks calendar, a dated task also appears there.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | What needs doing | |
| due_at | No | Due date as YYYY-MM-DD; omit for no due date | |
| contact_id | No | Link the task to this contact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state this is a non-read-only, non-destructive, closed-world operation. The description adds useful behavioral context beyond annotations: a dated task may also appear in a connected Google Tasks calendar, which is a meaningful external side effect.
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, front-loaded with the core action and followed by the relevant side effect. There is no wasted text.
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 simple three-parameter create tool with full schema description coverage and annotations covering safety, the description is complete enough. It also discloses the Google Tasks side effect, which is the main non-schema behavior an agent needs to know.
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 100%, and the schema already documents title, due_at, and contact_id with formats and meanings. The description repeats optional linkage and due date at a high level but does not add parameter semantics beyond the schema.
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 ("Create a task") and clarifies optional contact linkage and due date. It is clear, but it does not explicitly differentiate this tool from sibling update_task or delete_task beyond the verb "Create."
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 implies this is for creating new tasks, but it does not state when to use it versus alternatives such as update_task or list_tasks. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a contact along with its tasks and timeline activities. Deals are kept, so revenue history survives. This permanently deletes data and cannot be undone. Call without confirm to see what would be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually perform this. Call once WITHOUT it to receive a summary of exactly what will be destroyed, show that summary to the user, and only then call again with true. | |
| contact_id | Yes | The contact id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already marking this as destructive and not read-only, the description adds substantial context beyond annotations: what is deleted (contact, tasks, timeline activities), what is preserved (deals and revenue history), and that the action cannot be undone. It also explains the safe preview 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 four short sentences, front-loaded with the core action and scope, then moving to preservation and irreversibility. Every sentence carries useful information for a destructive tool, and the preview instruction ends with clear next-step guidance.
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 destructive two-parameter tool with no output schema, the description covers the key behavioral facts an agent needs: what is destroyed, what survives, that deletion is irreversible, and how to preview before confirming. Annotations and the schema already handle safety signaling and parameter specifics.
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 100%, so both parameters are already well documented in the schema, including the two-step confirm workflow. The description reinforces the preview behavior but does not add parameter meaning beyond the schema baseline.
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 gives a specific verb and resource ('Permanently delete a contact') and clarifies the cascade scope by naming tasks and timeline activities while preserving deals. It does not explicitly contrast with sibling deletion tools such as delete_task, but the contact-specific scope makes the target clear.
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 operational guidance for the confirm parameter: call without confirm to preview what would be removed, then call with confirm to proceed. It does not discuss when to choose deletion versus update_contact or other alternatives, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a pipeline and its stages. Only allowed when nothing would be lost: it is not the default (make another one the default first), it has no deals, no automation rule moves deals into it, and no website form files deals into it. Each refusal says which of these to resolve. This permanently deletes data and cannot be undone. Call without confirm first to see what would be deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually perform this. Call once WITHOUT it to receive a summary of exactly what will be destroyed, show that summary to the user, and only then call again with true. | |
| pipeline_id | Yes | The pipeline to delete, as returned by list_pipeline_stages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial context beyond destructiveHint=true: it states that deletion cascades to stages, is permanent, cannot be undone, and is guarded by preconditions. It also explains the refusal behavior and the two-step confirmation workflow.
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 front-loaded with the core action, then lists the safety preconditions, then the irreversible consequence, then the confirmation workflow. Every sentence adds operational value with no filler.
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 destructive mutation with no output schema, the description covers the action, cascade behavior, safety preconditions, refusal behavior, irreversibility, and the required confirmation sequence. An agent has enough information to call it correctly without further inference.
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 100%, so both parameters are already fully documented in the input schema. The description reinforces the confirm workflow but does not add parameter-level details beyond what the schema already provides.
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 and resource: 'Delete a pipeline and its stages.' This scope also implicitly distinguishes it from delete_pipeline_stage by making clear that this tool removes the entire pipeline including its stages.
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 gives explicit when-not conditions: not the default, no deals, no automation rule moves deals into it, and no website form files deals into it. It also tells the agent how to resolve the default-pipeline case ('make another one the default first') and notes that refusals explain what to fix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an open stage from a pipeline. Won and Lost cannot be deleted, and the last open stage of a pipeline cannot be deleted. If the stage has deals in it, move_to_stage_id is required and must be another stage of the SAME pipeline; every deal moves there first. Moving them does not trigger stage automations. Refused while an automation rule targets the stage. This permanently deletes data and cannot be undone. Call without confirm to see how many deals would move.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually perform this. Call once WITHOUT it to receive a summary of exactly what will be destroyed, show that summary to the user, and only then call again with true. | |
| stage_id | Yes | The stage to delete, as returned by list_pipeline_stages | |
| move_to_stage_id | No | Where its deals go: another stage id of the same pipeline. Required if the stage has deals |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: permanence and irreversibility, the refusal conditions, that moved deals do not trigger stage automations, and the dry-run-then-confirm protocol. This is exactly the kind of safety-relevant behavior an agent needs before a destructive call.
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?
Five dense sentences with the deletion scope and restrictions front-loaded, followed by the migration rule, refusal condition, irreversibility warning, and the preview workflow. No filler or repetition.
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?
No output schema exists, and the description compensates by explaining what the confirm-less call returns ('how many deals would move'). Combined with the refusal conditions and migration semantics, an agent has everything needed to invoke this safely.
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 100%, so the baseline would be 3; the description goes further by constraining move_to_stage_id to a stage of the SAME pipeline and stating that all deals migrate there before deletion. It also clarifies the confirm flag's purpose in prose, though most of this duplicates the schema text.
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 first sentence names a specific verb and resource ('Delete an open stage from a pipeline') and immediately scopes it with the 'open' qualifier, distinguishing it from deleting pipelines or renaming stages. An agent can identify the target operation without consulting 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?
Explicitly enumerates when deletion is refused (Won/Lost stages, the last open stage, stages targeted by an automation rule) and when move_to_stage_id is mandatory. It also prescribes a two-call workflow via the confirm flag, so the agent knows exactly how to sequence invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a task and its calendar event. This permanently deletes data and cannot be undone. To simply mark it finished, use set_task_status instead, which keeps the record. Call without confirm to see what would be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually perform this. Call once WITHOUT it to receive a summary of exactly what will be destroyed, show that summary to the user, and only then call again with true. | |
| task_id | Yes | The task id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds real value beyond them: it names the additional collateral (the associated calendar event is deleted too), reiterates irreversibility in plain language, and specifies the two-step dry-run/confirm protocol. These are the exact traits an agent needs before firing a destructive call.
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 compact sentences, front-loaded with the destructive nature and side effect, followed by the safer alternative and the confirm protocol. No filler or restatement of the title.
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 destructive tool with no output schema, the description covers purpose, side effects, irreversibility, alternative, and call sequence. The only gap is failure behavior (e.g., unknown task_id or missing permissions), which is minor and arguably inferable.
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 100% and the confirm parameter already documents the dry-run requirement, so the schema carries most of the load. The description reinforces the confirm semantics in prose ('Call without confirm to see what would be removed') but adds no new detail about task_id beyond the schema.
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 ('Permanently delete a task') and immediately names the side effect ('and its calendar event'), which distinguishes it from set_task_status and update_task in the sibling list. An agent can pick this tool without opening 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?
Explicitly routes the agent away from this tool when the goal is only to finish a task ('use set_task_status instead, which keeps the record'). It also prescribes the exact call sequence: call without confirm first, then again with confirm.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one call with its spoken transcript and any message the agent took during it. transcript is the conversation itself; messages is the separate intake or voicemail the agent saved, which many calls do not have. Long text is clipped and marked.
| Name | Required | Description | Default |
|---|---|---|---|
| call_id | Yes | The call id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, non-destructive, closed-world safety profile, so the description adds genuinely new behavior: long text is clipped and marked, and the `messages` collection is often absent. That truncation disclosure is exactly the kind of thing an agent cannot learn from structured fields.
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 tight sentences, front-loaded with the action, then the field semantics, then the truncation caveat. No filler and nothing repeated from the schema or annotations.
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?
There is no output schema, so the description carries the return-value burden and does it well: it separates `transcript` from `messages`, warns that `messages` is often empty, and flags clipping. A short note on how to tell clipping occurred or what an absent transcript looks like would make it complete.
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 one required parameter at 100% schema coverage, the schema already documents call_id. The description adds no format, sourcing, or example for the id, so baseline 3 applies.
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?
Specific verb and resource: "Fetch one call with its spoken transcript and any message the agent took during it." The singular "one call" implicitly separates it from the sibling list_calls, but no sibling is named explicitly, so the differentiation is inferential rather than stated.
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?
Usage is only implied: needing a single call's transcript. There is no explicit "use this when X" or "use list_calls instead when Y," and no prerequisites or notes about what call_id must come from.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single contact with its recent activity timeline (calls, emails, notes, outreach). The timeline is capped and says so when it is truncated. A timeline row is NOT necessarily something the contact said. Rows derived from a lead carry body_author saying who wrote the body: a manually logged lead is your own team's internal note, a web chat is your assistant's summary, a call is your voice agent's summary. Every row reads direction=inbound regardless. Never quote a body back to the contact, and never write "you said" or "you mentioned" about one, unless body_author says the contact wrote it.
| Name | Required | Description | Default |
|---|---|---|---|
| contact_id | Yes | The contact id | |
| activity_limit | No | Timeline rows, default 25, ceiling 100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, it discloses important behavioral details: the timeline is capped and signals truncation, row provenance is indicated by body_author, direction always reads inbound, and timeline bodies must not be quoted back unless the contact authored them. This is substantial safety-relevant context.
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 purpose is front-loaded in the first sentence, and the remaining sentences are focused on high-value timeline interpretation and quoting safety. It is somewhat dense and has mild overlap between the 'not necessarily something the contact said' and 'never quote' guidance, but the length is mostly earned.
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?
There is no output schema, and the description does a good job explaining the timeline portion of the response, including truncation and row semantics. It does not describe the contact object's fields, but for a get-by-id tool the remaining gaps are minor.
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 100%, so contact_id and activity_limit are already documented in the schema. The description adds useful context about timeline truncation but does not add parameter-level syntax or meaning beyond what the schema provides.
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: fetch a single contact, including its recent activity timeline. The word 'single' implicitly distinguishes it from list_contacts and search_contacts, though it does not name those sibling tools explicitly.
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?
Usage is implied by 'fetch a single contact', and the description gives strong downstream constraints about quoting timeline rows. However, it does not explicitly say when to use this tool versus list_contacts, search_contacts, or get_lead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single lead with its linked contact and, when the lead came from a phone call, that call, the spoken transcript, and any message the agent took. Whenever a lead has a message, the record also carries message_author saying WHO WROTE IT. That field is not decoration: a manually logged lead's message is your own team's private note about the person, a web chat's message is the chat assistant's summary, and a visibility checker's message is a generated scan result. Only when message_author is "the lead" are those their own words. Never quote a message back to the lead, and never write "you said" or "you mentioned" about one, unless message_author says the lead wrote it.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | The lead id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, non-destructive, closed-world, so the description isn't burdened with safety disclosure and instead adds real behavioral context: the record comes back joined with contact, call, transcript and message. It also discloses a non-obvious downstream trait — that message_author determines whether a message may be attributed to the lead — which nothing in the structured fields conveys.
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 purpose is front-loaded, which is good, but the paragraph spends most of its length on message_author and repeats the same conditional twice ('Only when message_author is "the lead"...' then 'unless message_author says the lead wrote it'). The aside 'That field is not decoration' is editorial filler that could be cut.
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?
With no output schema, the description carries the burden of describing return content, and it does so reasonably: contact, call, transcript, and message with author attribution. It does not say what happens for an unknown or deleted lead_id, and the enumeration of returned fields isn't exhaustive, which keeps it from a 5.
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?
One parameter at 100% schema coverage, so the baseline is 3. The description adds nothing about lead_id — no format, no hint that it typically comes from list_leads or a lead-creation response — so it neither compensates nor detracts.
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 ('Fetch a single lead') and enumerates the expansions it hydrates: linked contact, originating call, transcript, and taken message. It never names a sibling (list_leads, get_contact) to disambiguate, so it lands at 4 rather than 5.
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?
Usage guidance is entirely about how to interpret and re-use the returned message (never quote it back, never write 'you said' unless message_author is 'the lead'), which is genuinely useful. But there is no guidance on when to call this versus list_leads or search_contacts, nor any precondition such as needing a lead_id from a prior listing call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List phone calls handled for this account, most recent first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| since | No | ISO 8601 timestamp; only calls started at or after this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context that calls are account-scoped and returned most recent first, but it does not discuss pagination, filtering behavior, or return shape beyond ordering.
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?
It is a single tight sentence with zero wasted words, and the account scope and ordering behavior are front-loaded.
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 simple read-only list tool with annotated safety, complete parameter documentation, and no output schema, this is largely complete. The only minor gap is that it does not clarify filtering behavior or explain how the limit/ordering interact with results.
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 100%, so both parameters (limit and since) are already fully documented in the schema. The description adds no parameter-specific meaning beyond the general account and ordering context, making the baseline 3 appropriate.
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 (list phone calls) and adds scope (handled for this account) plus ordering (most recent first). It does not explicitly distinguish itself from the sibling get_call_transcript, which is the main remaining clarity gap.
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 implies this is the listing tool for calls, but it gives no explicit guidance on when to use it versus get_call_transcript or any other call-related workflow. There are no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts for this account, most recently active first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| lifecycle_stage | No | Contact lifecycle stage |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one genuinely new behavioral fact — the default sort order (most recently active first) — but says nothing about pagination behavior or total counts.
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?
One short sentence with no filler, and the resource is front-loaded ahead of the sort detail. Near-optimal density for what it says, though it could have used the same brevity to include a sibling pointer.
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 full annotation coverage and full schema coverage, this is minimally adequate: ordering and scope are stated. It leaves out result shape (no output schema exists) and does not clarify how it relates to search_contacts or list_leads, which an agent needs to route 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 description coverage is 100%, so both the limit (default 25, ceiling 100) and the lifecycle_stage enum are fully documented in the schema. The description adds no parameter detail beyond what the schema already carries, so baseline 3 applies.
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 ('List contacts') plus scope ('for this account'), which is more than a restatement of the title. It does not distinguish itself from the sibling search_contacts, so an agent still has to guess which enumeration tool to pick.
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 'for this account' scoping and 'most recently active first' ordering imply a browse/list use case rather than a filtered lookup, but no alternative is named and no when-not-to-use guidance is given. Usage must be inferred from the sibling list rather than from the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The emails and texts already exchanged with one lead, newest first, including whether each was delivered. Read this before composing a message so you do not repeat or contradict something they already received.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 20, ceiling 100 | |
| lead_id | Yes | The lead to message. Get one from list_leads or search_contacts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is read-only, non-destructive, and closed-world. The description adds useful behavioral detail beyond that: results are newest first and include delivery status, which helps the agent understand the returned history.
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, front-loaded with the resource and ordering, then the operational reason to use it. Every sentence adds value with no repetition or filler.
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 read-only list tool with full schema coverage and annotations, the description supplies the key missing context: what is returned, ordering, delivery status, and why to call it before composing. Nothing essential is omitted.
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 100%, so both parameters are documented in the schema. The description reinforces that the tool operates on one lead, but does not add new meaning about lead_id or limit beyond what the schema already provides.
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?
It states the exact resource and scope: emails and texts already exchanged with one lead, newest first, with delivery status. This clearly separates it from the sibling send_lead_email and send_lead_sms tools, which compose rather than list messages.
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 gives a clear when-to-use condition: read this before composing a message so you do not repeat or contradict prior communication. It does not explicitly name exclusions or alternatives, but the read-before-writing context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List leads for this account, newest first. Filter by source, status, or a created-after timestamp. Returns lead records as data. Whenever a lead has a message, the record also carries message_author saying WHO WROTE IT. That field is not decoration: a manually logged lead's message is your own team's private note about the person, a web chat's message is the chat assistant's summary, and a visibility checker's message is a generated scan result. Only when message_author is "the lead" are those their own words. Never quote a message back to the lead, and never write "you said" or "you mentioned" about one, unless message_author says the lead wrote it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| since | No | ISO 8601 timestamp; only leads created at or after this | |
| source | No | Lead source | |
| status | No | Lead status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the read-only safety profile; the description adds substantial context beyond that: default newest-first ordering, that records come back as data, and a detailed disclosure that a record's message_author varies by lead origin (manual note vs. chat summary vs. scan output vs. the lead's own words). It even sets a downstream behavioral constraint (never quote a message back unless the lead wrote it), which is exactly the kind of non-schema information an agent cannot get elsewhere.
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 first sentence is well front-loaded with scope and ordering, but roughly two-thirds of the text is a single field's semantics, delivered with caps emphasis and repeated prohibitions ("Never quote... never write 'you said'..."). The content is valuable but over-weighted for a list tool whose primary job is enumeration.
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?
With no output schema, the description does carry some of the return burden ("lead records as data", plus the message_author field contract), and it covers the safety profile via annotations. It omits pagination/cursor behavior and whether counts or truncation are signaled, which is a real but modest gap for a 4-optional-param list 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 100%, so all four parameters (including the limit ceiling of 100) are already documented in the schema. The description restates the source/status/since filters without adding syntax or interaction detail, and never mentions limit at all. Baseline 3 applies.
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 ("List leads for this account") plus an ordering guarantee ("newest first"), which is enough to separate it from get_lead (single record) and list_lead_messages. It never names a sibling explicitly, so differentiation is inferred from the read/list semantics rather than stated.
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 gives concrete filtering axes (source, status, created-after) that imply when the tool is useful, but offers no when-not guidance and never points to list_lead_messages or get_lead as the alternative when the agent wants message bodies or a single lead. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The verified mailboxes this account can send email from. Use one of these ids as mailbox_id for send_lead_email. Unverified mailboxes are listed but cannot send.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still earns credit by disclosing a non-obvious behavioral trait beyond the annotations: unverified mailboxes appear in the listing but cannot actually send. That is exactly the kind of surprise an agent needs warned about.
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 short sentences, no filler, and the core identity of the tool comes first, followed by the consumer instruction and the caveat. 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?
For a zero-parameter, read-only listing with no output schema, the description supplies the essentials: what is returned (mailboxes and their ids) and the verified/unverified distinction. It could be marginally better by hinting at the shape of each entry, but nothing needed to call 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?
There are zero parameters, so the baseline is 4. The description goes slightly beyond baseline by explaining the meaning of the returned id and its linkage to the mailbox_id field in send_lead_email, which is semantics rather than schema repetition.
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 names the resource precisely: 'The verified mailboxes this account can send email from.' It is not a literal verb-first phrasing, but the list semantics are unmistakable and it is clearly differentiated from send_lead_email, which it names as the consumer. The added distinction between verified and unverified mailboxes sharpens the purpose further.
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 tells the agent exactly what to do with the result: 'Use one of these ids as mailbox_id for send_lead_email.' That is a concrete downstream routing instruction, not just implied usage. It stops short of stating when NOT to call it, but for a zero-parameter listing tool feeding a single sibling, the context is effectively complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show where Meta (Facebook and Instagram) lead-ad leads go. Returns the Pages this account has connected, each with pipeline_id (null = the account default pipeline), and every lead form that has delivered at least one lead, with its own pipeline_id override (null = same as its Page), an optional label, and its lead count. A lead goes to its form's pipeline if set, else its Page's, else the default. Forms only appear after their first lead (Meta does not let this app list a Page's forms), so a brand-new form cannot be routed yet. Pipeline names and ids come from list_pipeline_stages.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, the description discloses important behavior: null pipeline_id semantics, the Page-to-form routing fallback order, form visibility only after the first lead, and the Meta API limitation that prevents listing forms before they receive a lead. These details materially affect how an agent interprets results.
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 front-loaded with the core purpose, then adds the return structure, routing precedence, limitation, and dependency in a compact sequence. Every sentence contributes useful meaning without repetition.
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?
With no output schema, the description carries the burden of explaining returns, and it does so thoroughly: Pages, forms, pipeline_id overrides, labels, lead counts, and fallback routing. Annotations cover safety, and the description covers the behavioral gaps an agent needs.
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 baseline is 4. The description focuses appropriately on return semantics and routing behavior rather than 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 states a specific verb and resource: showing where Meta lead-ad leads are routed. It clearly distinguishes this read-view tool from routing mutation tools like set_meta_lead_route and explicitly points to list_pipeline_stages for pipeline names and ids.
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 gives clear context for when this view is useful: inspecting connected Pages, form-level overrides, fallback routing, and the Meta limitation on brand-new forms. It does not explicitly say when not to use it or name set_meta_lead_route as the mutation alternative, but the surrounding guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deals for this account with their pipeline stage name, most recently updated first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| status | No | Deal status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond annotations — results are ordered by most recently updated — but says nothing about default row count behavior, filtering effect of status, or what happens at the ceiling.
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?
One sentence with zero filler: verb and scope lead, returned fields and ordering follow. Nothing could be removed without losing information.
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 2-param read-only list tool with a fully described schema and no output schema, the description covers what it returns and how results are ordered. It stops short of explaining how the status filter interacts with the 'open/won/lost' lifecycle or pagination via limit, which would have made it complete.
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 100%, so both the limit (max 25 default, ceiling 100) and the status enum are already documented in the schema. The description adds no meaning to either parameter, which matches the baseline 3 for a fully documented 2-parameter schema.
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 (list deals) scoped to 'this account', and even names the returned attribute (pipeline stage name) and sort order. The resource is clearly distinct from sibling list_* tools such as list_contacts and list_leads, though the description never explicitly contrasts with list_pipeline_stages.
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?
Usage is implied by 'for this account' (account-scoped enumeration) but there is no explicit when-to-use guidance, no mention of when to prefer a narrower sibling, and no note of what the status filter is for. An agent must infer the selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List this account pipeline stages in board order. Each row carries the stage id plus the pipeline it belongs to: pipeline_id, pipeline_name, and pipeline_is_default. Call this before move_deal_stage and before create_pipeline_stage — both need an id from here. An account can have more than one pipeline, and stage names and positions repeat across them, so group by pipeline_id rather than assuming one board. A deal can only move between stages of its OWN pipeline, and pipeline_is_default marks the one new deals are filed into.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable domain behavior: each row carries pipeline_id, pipeline_name, and pipeline_is_default, and a deal may only move between stages in its own pipeline.
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 purpose is front-loaded and every sentence adds useful information about usage or returned fields. It is slightly dense but not 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?
With no parameters, no output schema, and read-only annotations, the description supplies the missing context an agent needs: row fields, multiple-pipeline grouping, default-pipeline meaning, and the stage-move constraint.
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 input parameters, so there are no input semantics to explain. The description appropriately shifts to output semantics instead, describing the fields each row carries.
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: listing pipeline stages for the account in board order. It distinguishes the tool from siblings by naming the exact row fields returned and by tying it to move_deal_stage and create_pipeline_stage.
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?
Explicitly says to call this before move_deal_stage and create_pipeline_stage because both need a stage id from here. It also warns that multiple pipelines may exist and that stage names/positions repeat across pipelines, giving clear grouping guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List follow-up tasks for this account, soonest due first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| status | No | Task status | |
| due_before | No | ISO date; only tasks due on or before this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the default sort ('soonest due first'), but says nothing about result volume, truncation, or whether cancelled/done tasks are included by default.
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?
A single front-loaded sentence with zero filler; scope and ordering both land before the reader needs anything else.
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 three-parameter, read-only list tool with full schema coverage and annotations covering safety, the description supplies the one thing structured fields can't: the default ordering. Only the default status filter behavior is left unstated.
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 100%, so limit, status and due_before are fully documented in the schema. The description's only implicit tie to parameters is the due-date ordering, which adds no syntax or constraints beyond what the schema already provides.
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?
Uses a specific verb ('List') plus resource ('follow-up tasks'), and scopes it ('for this account') while stating the sort order. It doesn't explicitly differentiate from create_task/update_task/delete_task siblings, but the read semantics are unmistakable.
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?
'For this account' implies the usage context, but there is no explicit when-to-use guidance, no mention of alternatives (e.g. filtering by status</>, or reaching for get/list siblings), and no prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a note, call, voicemail, meeting or text to a contact timeline. This is how you record something that already happened. It also bumps the contact to the top of the list.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What happened, in plain words | |
| kind | Yes | What kind of activity this was | |
| contact_id | Yes | The contact id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuine non-obvious behavior: logging bumps the contact to the top of the list, a side effect the agent would not otherwise know. It doesn't state validation or failure behavior, keeping it below 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 short sentences with no filler. The core action leads, and the side effect is appended only after the primary purpose is clear.
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 three-required-parameter write tool with full schema coverage and no output schema, the description covers purpose, kind options, and a key side effect. Remaining gaps (error behavior for an invalid contact_id, duplicate handling) are minor and partly carried by the schema.
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 100%, so the schema already documents all three parameters, making 3 the baseline. The description's enumeration of kinds loosely maps to the 'kind' enum ('text' vs. the actual 'sms' value), which is a minor but not harmful addition.
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 ('Add a note, call, voicemail, meeting or text to a contact timeline') and enumerates the activity kinds, so the agent knows exactly what gets created. It does not name the closest sibling (log_outreach), so differentiation is only implicit through the 'already happened' framing.
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?
'This is how you record something that already happened' gives an implied when-to-use rule, contrasting past-tense logging with presumably forward-looking create_task work. However, no sibling is named and no exclusion is stated, leaving the agent to guess between this and log_outreach for outbound contact records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that you texted, called or left a voicemail for a contact, and optionally create a dated follow-up task. The follow-up date is computed in this account timezone, not UTC.
| Name | Required | Description | Default |
|---|---|---|---|
| channel | Yes | How you reached out | |
| contact_id | Yes | The contact id | |
| contact_name | No | Name to write into the log line | |
| followup_days | No | Create a follow-up task this many days from today; omit for no follow-up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (write, non-destructive, closed-world). The description adds a genuinely non-obvious behavioral fact beyond them: the follow-up date is computed in the account timezone, not UTC. It does not disclose what the call returns (log entry, task id) or whether the log entry is deduplicated.
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, zero waste. The core action is front-loaded and the timezone caveat is placed immediately after the follow-up clause it qualifies.
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 simple four-parameter write with no output schema, the description covers what is recorded, the channels available, and the follow-up semantics including timezone handling. Only the response shape / side effects on the contact record are left implicit, which is a minor gap at this 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?
Schema coverage is 100%, so baseline is 3; the description earns an extra point by clarifying that followup_days resolves against the account timezone rather than UTC, which the schema description ('this many days from today') leaves ambiguous. It says nothing extra about channel or contact_name beyond their schema descriptions.
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 ('Record that you texted, called or left a voicemail for a contact') and names the optional side effect (creating a follow-up task). It is concrete enough to distinguish from create_task or log_activity, but it never explicitly names those siblings as alternatives.
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?
Usage is implied rather than stated: the reader infers this is the tool for after an outreach attempt, and that followup_days is the way to schedule follow-up work instead of calling create_task. There is no explicit when-to-use/when-not or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a deal along the pipeline. Get stage ids from list_pipeline_stages and deal ids from list_opportunities. The stage must belong to the same pipeline the deal is already in — check the stage pipeline_id against the deal pipeline_id, since stage names repeat across pipelines. This tool moves a deal WITHIN its pipeline; it cannot move one to a different pipeline. Whether the deal counts as won or lost is decided by the stage you move it into, not by anything you pass here.
| Name | Required | Description | Default |
|---|---|---|---|
| stage_id | Yes | The target stage id, as returned by list_pipeline_stages | |
| opportunity_id | Yes | The deal id, as returned by list_opportunities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly=false, destructive=false, openWorld=false, so the mutation/safety profile is already covered; the description adds real behavioral context on top — the cross-pipeline constraint, the fact that stage names repeat so name matching is unsafe, and that won/lost status is a consequence of the target stage rather than a parameter. It stops short of saying what side effects occur (notifications, automations, history entries) or what an invalid pipeline mismatch returns.
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 action, then prerequisites, then the hard constraint, then the scoping exclusion, then the won/lost caveat. Five short sentences with no filler and no repetition of the title.
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 mutation with no output schema, the description covers prerequisites, validity constraints, and the conceptual gotcha about stage names and won/lost. The remaining gap is return/error behavior on a pipeline mismatch, which is minor given the otherwise thorough constraint coverage.
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 100%, so both parameters are already documented; the description goes further by explaining that stage ids come from list_pipeline_stages and must belong to the deal's own pipeline, and by warning that stage names are not unique across pipelines. That is genuine semantic value beyond the schema's one-line param descriptions.
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?
Specific verb (move) plus resource (deal) plus the axis it moves along (pipeline stage), and it explicitly scopes out what it cannot do (change pipelines). An agent can distinguish this from update_task, reorder_pipeline_stages, or any sibling without opening a 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 names the exact prerequisite lookups (list_pipeline_stages for stage ids, list_opportunities for deal ids) and states the validity condition — stage pipeline_id must equal deal pipeline_id. It also states the exclusion: it cannot move a deal to a different pipeline, so an agent knows when this tool is the wrong choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a pipeline. Its stages, deals and default status do not change. Get pipeline_id from list_pipeline_stages. Refused if another pipeline in this account already has that name, ignoring case.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new pipeline name | |
| pipeline_id | Yes | The pipeline id, as returned by list_pipeline_stages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-destructive write operation, and the description adds useful behavioral detail beyond that: stages, deals, and default status are unaffected, and the call is refused if another pipeline in the account already has the name ignoring case. It does not describe the response or permissions required, but the key side effects and failure mode are disclosed.
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 short sentences with no waste. The purpose is front-loaded, followed by side effects, parameter sourcing, and the refusal condition in a logical order.
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 simple two-parameter rename operation with annotations and full schema coverage, the description covers the essential behavioral traits: what changes, what does not, where the ID comes from, and when the call fails. No output schema exists, so return-value detail is not required.
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 100%, so both parameters are already documented structurally. The description adds meaningful semantics beyond the schema by explaining where pipeline_id comes from and that name must be unique within the account ignoring case.
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: 'Rename a pipeline.' It is clearly distinct from siblings such as create_pipeline, delete_pipeline, and rename_pipeline_stage, so an agent can identify the operation without opening 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 states the prerequisite for pipeline_id ('Get pipeline_id from list_pipeline_stages') and the refusal condition for duplicate names, giving clear usage context. It does not explicitly contrast with alternatives beyond the implicit rename action, but the operation is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a stage. Any stage can be renamed, including Won and Lost (for example "Retained" and "Declined"); a stage keeps its role, so deals and lead statuses are unaffected. Get stage_id from list_pipeline_stages. Refused if another stage in the same pipeline already has that name, ignoring case.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new stage name | |
| stage_id | Yes | The stage id, as returned by list_pipeline_stages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses important behavior: renaming preserves the stage's role, deals and lead statuses are unaffected, and duplicate names in the same pipeline are refused case-insensitively. These details are directly relevant to safely invoking a mutation tool.
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 three focused sentences with no wasted text. The core action and key constraints are front-loaded, and the parenthetical examples clarify rather than pad.
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 simple two-parameter mutation with an output schema absent but not needed, the description covers the action, ID source, allowed scope, side effects, and failure condition. An agent has enough information to call it 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 100%, so the schema already documents both parameters. The description adds meaningful semantics by specifying the source of stage_id and the case-insensitive uniqueness constraint on name.
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: rename a pipeline stage. It clearly distinguishes this from sibling operations such as rename_pipeline or create_pipeline_stage by focusing on an existing stage identified by stage_id.
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 tells the agent how to obtain the required stage_id via list_pipeline_stages and notes that all stages, including Won and Lost, can be renamed. It does not explicitly compare against alternatives like rename_pipeline, but the resource distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the left-to-right order of a pipeline's OPEN stages. Pass open_stage_ids as the COMPLETE list of that pipeline's stages that are neither Won nor Lost, in the new order; Won and Lost always stay last and must not be included. The first stage is where new leads land. Read the stages with list_pipeline_stages immediately before calling. Refused if the list is not exactly the current open stages. To also be refused when someone has REORDERED them since you read them, pass current_order; without it, your order simply replaces theirs.
| Name | Required | Description | Default |
|---|---|---|---|
| pipeline_id | Yes | The pipeline id, as returned by list_pipeline_stages | |
| current_order | No | Optional but recommended: the OPEN stage ids (not Won or Lost) in the order you last read them. If given, the reorder is refused when someone has changed the order since, instead of overwriting their change. Resend it on every retry | |
| open_stage_ids | Yes | Every open stage id of that pipeline, in the new order |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare that this is a non-read-only, non-destructive, closed-world mutation. The description adds real behavioral disclosure beyond that: the operation is refused unless the id list exactly matches current open stages, and omitting current_order means your order overwrites someone else's change. That overwrite risk is precisely the kind of consequence an agent needs to know.
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 the key constraint (OPEN stages only), then builds out ordering, exclusion of Won/Lost, the read-first prerequisite, and the optional concurrency guard. Dense but every sentence carries distinct information with no repetition.
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?
With no output schema, three parameters at full schema coverage, and annotations covering the safety profile, the description fills the remaining gaps: the pre-read requirement, the refusal semantics, and the concurrency behavior. Nothing needed to call 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?
Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: that the first stage is where new leads land, and the practical guidance to resend current_order on every retry. The refusal condition tied to open_stage_ids completeness further clarifies the required array's meaning.
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 with precise scope: 'Set the left-to-right order of a pipeline's OPEN stages.' It distinguishes itself from siblings like move_deal_stage (single deal) and list_pipeline_stages (read), so an agent can route correctly without opening 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?
Explicitly tells the agent to read the stages with list_pipeline_stages immediately before calling, that Won and Lost stages must be excluded and always stay last, and when to pass current_order (to avoid clobbering a concurrent reorder) versus omitting it (last-write-wins). All when/when-not conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find contacts by name, email, or phone. A phone number matches however it is typed: "(864) 555-1234", "864-555-1234" and "+18645551234" all find the same contact.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows, default 25, ceiling 100 | |
| query | Yes | A name fragment, email address, or phone number. Needs at least two real characters — a one-character search matches most of the account and is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint false and openWorldHint false, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: phone matching is format-insensitive across '(864) 555-1234', '864-555-1234' and '+18645551234', which an agent could not derive from structured fields.
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, zero filler, with the core purpose front-loaded and the clarifying example immediately after. Every sentence carries information an agent needs.
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-only search with no output schema, the definition covers purpose and matching behavior well. It does not state what a result set looks like or how multiple partial matches are ordered, a minor gap given the absent output schema.
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 100%, so baseline is 3, but the description earns an upgrade by explaining matching semantics for the query parameter — that a phone number matches regardless of formatting — which the schema text does not state. The limit parameter is only covered by the schema (default 25, ceiling 100), not the description.
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 ('Find contacts') plus the searchable attributes, which cleanly separates it from create/update/delete siblings in intent. It never names list_contacts or get_contact, so the boundary between searching, listing, and fetching a single record is left to inference.
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 implies search-by-fragment usage but gives no explicit when-to-use or when-not-to-use guidance, and no sibling alternative is named. An agent has to guess whether list_contacts or get_contact is the better call when it already has an exact identifier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one email to a lead from one of this account's verified mailboxes and record it on the lead. Use list_mailboxes to get a mailbox id. You do not choose the recipient address; it is read from the lead record. Sending is refused if the address has opted out. The lead is moved to contacted automatically if it was still new.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Plain text body. | |
| lead_id | Yes | The lead to message. Get one from list_leads or search_contacts. | |
| subject | Yes | Subject line. | |
| mailbox_id | Yes | Which verified mailbox to send from. Get one from list_mailboxes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing three non-obvious behaviors: sending is refused when the address has opted out, the message is recorded on the lead, and a new lead is auto-moved to contacted. These are exactly the side effects and failure modes an agent needs before invoking a destructiveHint=true mutation.
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 short sentences, all front-loaded with the action first, then the prerequisite, then the constraints and side effects. No filler.
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 4-required-param mutation with no output schema, the description covers prerequisites, refusal conditions, and resulting state changes, so an agent can call it safely and predict its effects. Nothing essential 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 100%, so the baseline is 3; the description adds value by clarifying what is NOT a parameter (the recipient address) and by requiring the mailbox to be verified. It doesn't describe subject/body constraints, but the schema already covers those.
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 (send one email), the resource (a lead), the constraint (from a verified mailbox), and the side effect (recorded on the lead). The word 'email' also implicitly separates it from send_lead_sms without naming it.
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 operational guidance: use list_mailboxes to obtain a mailbox id, and explicitly notes the recipient address is not chosen by the caller but read from the lead record. It doesn't explicitly say when to prefer this over send_lead_sms, but the channel verb makes the alternative clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one SMS to a lead, from this account's registered number, and record it on the lead. You do not choose the recipient number or the sending number: both are resolved from the lead record and the account. Sending is refused unless the recipient has a recorded opt-in, is not on the do-not-text or opt-out list, and it is inside their local allowed hours. Those checks run on the server and cannot be overridden by anything you pass. A refusal is not a fault to report as an outage, it is the answer. Set message_class to marketing for anything promotional, a follow-up, or anything with a call to action; transactional is only for a direct reply about what this person contacted us about. If you are unsure, it is marketing. An opt-out line is added automatically, so do not write one.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The message. Keep it under 320 characters. Do not include an opt-out instruction, one is appended for you. | |
| lead_id | Yes | The lead to message. Get one from list_leads or search_contacts. | |
| message_class | Yes | marketing for promotional or follow-up messages (needs written opt-in), transactional for a direct reply about their own enquiry. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the destructiveHint=false/readOnlyHint=false annotations: recipients and senders are server-resolved, opt-in/DNC/quiet-hours gates run server-side and cannot be overridden by parameters, and a refusal is a normal answer rather than an outage. It also discloses that an opt-out line is appended automatically, which prevents a real misuse.
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?
Dense but front-loaded: what it does, then the hard constraints, then the classification rule, then the opt-out reminder. A couple of sentences duplicate the schema's wording on the opt-out line, which is the only wasted space.
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 destructive, side-effecting send with no output schema, the description covers the things that actually cause failure: resolved numbers, compliance gates, refusal handling, and message classification. It never says what comes back on success (message id, delivery status), which would have made it fully self-sufficient.
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 100%, so baseline is 3, but the description adds real meaning the schema does not: it explains why lead_id/recipient resolution is fixed, and supplies a tie-breaking rule for message_class classification that the enum description alone lacks. The body-length and opt-out constraints are restatements of schema text.
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?
Specific verb and resource: 'Send one SMS to a lead... and record it on the lead,' and it immediately clarifies that neither phone number is agent-chosen. It is clearly distinguishable from send_lead_email and the list_lead_messages siblings by the medium and the one-message 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?
Gives an explicit decision rule for the only genuinely ambiguous choice ('marketing for anything promotional, a follow-up, or anything with a call to action... If you are unsure, it is marketing') and states the preconditions under which sending occurs. It stops short of naming send_lead_email as the alternative channel, which is the one routing choice an agent might still have to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a pipeline the default: new leads from calls, web chat, forms without their own pipeline and Meta lead ads, and deals created without a pipeline_id, land in its first stage from now on. Exactly one pipeline is the default (pipeline_is_default in list_pipeline_stages). Existing deals do not move. Calling it on the current default changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| pipeline_id | Yes | The pipeline to make the default, as returned by list_pipeline_stages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say non-readonly, non-destructive, closed-world. The description goes well beyond: it names the invariant (exactly one default, observable via pipeline_is_default in list_pipeline_stages), states existing deals do not move, and states the idempotent no-op behavior on the current default. An agent knows exactly what will and won't change.
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 verb and resource, then the downstream effects. The single long sentence packs several distinct facts (affected channels, invariant, no-move, no-op), which is dense but every clause carries meaning; a short bulleted split would be slightly easier to scan.
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 one-parameter mutation with no output schema, the description covers the essential behavioral surface: effects, invariant, and idempotency. Return value/permission requirements are not described, but there is no output schema to explain away and the annotation set covers safety.
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 100% and the schema already says the pipeline_id comes from list_pipeline_stages. The description reinforces the source and clarifies that it identifies a single pipeline, but adds little syntax or format detail beyond the structured field.
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 ('Make a pipeline the default') and then enumerates exactly which inbound paths are affected and what happens to them ('land in its first stage from now on'). It is clearly distinguished from rename_pipeline and reorder_pipeline_stages by describing the default-state semantics rather than structural edits.
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 clear conditions: it applies to new leads/deals without their own pipeline, and explicitly says calling it on the current default changes nothing. It also clarifies the invariant that exactly one pipeline can be default. It stops short of naming a sibling to use for renaming or reordering, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a lead between new, contacted and closed. Use list_leads or get_lead first to find the lead id.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | The new status | |
| lead_id | Yes | The lead id, as returned by list_leads or get_lead |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation and safety profile are covered structurally. The description adds that this is a state transition and that a lead id must be sourced first, but says nothing about side effects (notifications, automation triggers on 'closed' or 'converted') or whether transitions can be reversed. With annotations carrying the safety burden, this is adequate but thin.
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 tight sentences with zero waste; the action and state space come first, followed by the prerequisite lookup. Nothing needs to be re-read or reordered.
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 tool with full schema coverage and mutation annotations, the description plus structured fields give an agent essentially everything needed to invoke it. The remaining gaps are the omitted 'converted' status and any note on side effects of closing or converting a lead.
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 100%, so both parameters are documented and the status enum fully enumerates values, establishing the baseline of 3. The description only restates the lead_id provenance already present in the schema and lists status values incompletely (omitting 'converted'), adding no real semantics beyond the structured data.
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 (move) and resource (a lead) plus the state space, which clearly separates it from siblings like update_contact or set_task_status. However, it names only 'new, contacted and closed' while the schema enum also allows 'converted', so the stated scope is slightly narrower than the tool's actual capability.
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?
Explicitly tells the agent to call list_leads or get_lead first to obtain the lead id, naming the sibling tools to use. It gives a clear precondition but no exclusion guidance (e.g., when not to set status, or that other tools handle deal stages instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose which pipeline new Meta lead-ad leads go to. Give page_id alone to set the Page's route (every form on that Page), or page_id and form_id to override one form. pipeline_id null clears the route at that level (a Page falls back to the account default; a form falls back to its Page). Only connected Pages, and only forms that have already sent a lead, can be routed: get both from list_meta_lead_routes. Clearing (pipeline_id null, no form_id) also works for a Page that is no longer connected (stale_pages) and clears that Page's form routes too, since leftover routes would otherwise block deleting the pipeline they name. Existing deals do not move; it applies to leads that arrive from now on.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | No | A form id from list_meta_lead_routes, to override just that form | |
| page_id | Yes | A connected Page id from list_meta_lead_routes | |
| pipeline_id | Yes | Target pipeline id from list_pipeline_stages, or null to clear |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false); the description adds the real behavioral weight: routing preconditions (only connected Pages, only forms that have sent a lead), the fallback chain when a route is cleared, the cascade side effect (clearing a Page also clears its form routes, to unblock pipeline deletion), and that existing deals do not move. That is exactly the beyond-annotations context an agent needs.
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 purpose, then progressively discloses the scoping modes, clearing semantics, and preconditions. Dense and mostly earns its words, but the trailing stale-Pages/pipeline-deletion rationale is a long subordinate clause that could be trimmed without losing actionable information.
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 3-parameter configuration tool with no output schema, it covers everything an agent needs: preconditions, the two write modes, clearing behavior, cascade effects, and non-effects on existing deals. No return-value documentation is required since no output schema exists.
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 100%, so the baseline is 3, but the description genuinely adds meaning: page_id alone vs. page_id+form_id changes the scope of the write, and pipeline_id=null is a clearing operation with defined fallback semantics. It does not add format/syntax details beyond the schema, which is fine at this coverage level.
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: 'Choose which pipeline new Meta lead-ad leads go to.' It names the sibling tool to consult first (list_meta_lead_routes), so the agent can separate this configuration tool from the listing 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?
Explicitly distinguishes the two invocation modes (page_id alone = whole Page; page_id+form_id = single-form override), states when to use the null pipeline_id to clear, and names the prerequisite lookup tool. It even carves out the special case for stale Pages that can only be cleared, not set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a task done or put it back to open. Completing it removes its calendar event, because the calendar shows open work only; reopening puts the event back.
| Name | Required | Description | Default |
|---|---|---|---|
| done | Yes | true to complete, false to reopen | |
| task_id | Yes | The task id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnly=false, destructive=false) by disclosing the non-obvious side effect that completing removes the task's calendar event, plus the rationale (the calendar shows open work only) and that the effect is reversible via reopen. That side-effect and reversibility information is exactly what an agent needs before mutating state.
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, zero waste, front-loaded with the action and then the side effect and its rationale. Every clause carries information the agent could not get from the 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?
For a simple two-required-parameter mutation tool with no output schema and full schema coverage, the description covers action, effect, reversibility, and rationale. It does not say what is returned or how failures (e.g. unknown task_id) behave, which is a minor remaining gap.
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 100% and already documents both parameters, but the description adds meaning by tying each value to a consequence: completing (done=true) deletes the calendar event, reopening (done=false) restores it. That goes beyond 'true to complete, false to reopen'.
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 ('Mark a task done or put it back to open'), and the state-toggle framing makes it unambiguously distinct from update_task (field edits) and delete_task (removal) among its siblings.
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?
Covers both usage directions explicitly — completing versus reopening — with the implication that this is the tool for status changes. It stops short of naming update_task or delete_task as the alternatives, so there are no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a contact: name, email, phone, lifecycle stage, company, or address (address_line1, address_line2, city, state, postal_code, country). Only the fields you send are changed; anything you omit keeps its current value. Send an empty string to clear a field. A contact must keep at least one of name, email or phone.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | New city (max 100 characters). Set to an empty string to clear. | |
| No | New email; empty string clears it | ||
| phone | No | New phone; empty string clears it | |
| state | No | New state (max 100 characters). Set to an empty string to clear. | |
| company | No | New company (max 300 characters). Set to an empty string to clear. | |
| country | No | New country (max 100 characters). Set to an empty string to clear. | |
| last_name | No | New last name; empty string clears it | |
| contact_id | Yes | The contact id, as returned by list_contacts or search_contacts | |
| first_name | No | New first name; empty string clears it | |
| postal_code | No | New postal code (max 100 characters). Set to an empty string to clear. | |
| address_line1 | No | New address line 1 (max 300 characters). Set to an empty string to clear. | |
| address_line2 | No | New address line 2 (max 300 characters). Set to an empty string to clear. | |
| lifecycle_stage | No | Move the contact to this lifecycle stage |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-structured behavior: omission preserves values, empty string clears a field, and the invariant that name/email/phone cannot all be removed — that last constraint is critical and appears nowhere in the schema.
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 tight sentences: what can be changed, how omission is treated, how to clear, then the constraint. The most consequential rule (partial update) is front-loaded and nothing is repeated from the 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?
For a 13-parameter mutation with no output schema, the description covers the mutation model and the key validation invariant. It leaves out error behavior for an unknown contact_id and whether clearing counts as a destructive change, which would have made it complete.
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 100%, so the baseline is 3, but the description goes beyond the schema by explaining partial-update semantics across the 13 fields and the mandatory remaining identifier. It adds useful meaning rather than restating per-parameter types.
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 ('Edit') plus resource ('a contact') and enumerates the editable field groups, including the address sub-fields. The verb alone separates it from create_contact, delete_contact and get_contact in the sibling list, so an agent can pick it without opening 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?
'Only the fields you send are changed; anything you omit keeps its current value' gives a clear usage model that distinguishes a patch-style edit from a full replace. It doesn't explicitly name when to prefer it over siblings (e.g., create_contact for new records) or state prerequisites like lookup via get_contact, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a task title and/or due date. Both are replaced, so send the title even when only the date is changing. Any linked calendar event is reconciled to match.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | The task title, existing or new | |
| due_at | No | Due date as YYYY-MM-DD; omit to clear the due date | |
| task_id | Yes | The task id, as returned by list_tasks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare it is a non-read-only, non-destructive, closed-world mutation. The description adds genuinely non-obvious behavior: replace-not-patch semantics for both fields, and a cross-resource side effect ("Any linked calendar event is reconciled to match") that no annotation conveys. It does not cover reversibility or failure modes, so 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 short sentences, front-loaded with the operation and followed by the two behavioral facts an agent would otherwise get wrong. Nothing redundant or 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 3-parameter mutation with no output schema, the description covers purpose, replace semantics, and the calendar-event side effect — enough to call it correctly. It does not describe the returned task representation or whether the calendar reconciliation can fail, a minor remaining gap.
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 100%, so the baseline is 3. The description earns above baseline by explaining why title is required even when only the date changes, which is a semantic the schema alone cannot convey; the omit-to-clear behavior for due_at is left entirely to the schema.
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 (change) and resource (task) plus the exact editable fields (title and/or due date), which cleanly separates it from siblings like set_task_status, delete_task, or create_task. It never names an alternative sibling explicitly, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Both are replaced, so send the title even when only the date is changing" gives concrete calling guidance for the common edge case. It does not state when to prefer this over set_task_status or how to handle status changes alongside title edits, so no explicit exclusions.
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.
list_leads1 field changedInput schema / properties / source / enumPrevious value: -[
- "call",
- "website_form",
- "website_chat",
- "meta",
- "barguard",
- "external_app",
- "manual",
- "ai_visibility_checker"
-]New value: +[
+ "call",
+ "website_form",
+ "website_chat",
+ "meta",
+ "barguard",
+ "external_app",
+ "manual",
+ "ai_visibility_checker",
+ "booking"
+]create_contactcreate_dealcreate_leadcreate_pipelinecreate_pipeline_stagecreate_taskdelete_contactdelete_pipelinedelete_pipeline_stagedelete_taskget_call_transcriptget_contactget_leadlist_callslist_contactslist_lead_messageslist_leadslist_mailboxeslist_meta_lead_routeslist_opportunitieslist_pipeline_stageslist_taskslog_activitylog_outreachmove_deal_stagerename_pipelinerename_pipeline_stagereorder_pipeline_stagessearch_contactssend_lead_emailsend_lead_smsset_default_pipelineset_lead_statusset_meta_lead_routeset_task_statusupdate_contactupdate_task
Add one secure layer between your agents and this server.