Add to CRM

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

Annotations already declare the write/destructive/open-world profile, and the description adds real value on top: an upfront domain dedupe check, default field settings and default tags applied automatically, and consumption of one lookup credit when details aren't cached. It stops short of explaining what happens when a duplicate is found (overwrite, skip, or require confirmation), which matters given destructiveHint=true.

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 what the tool does, then behavior and cost. Every clause carries information the agent needs; no filler or 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?

With an output schema present, return values need no explanation, and the credit cost, dedupe step, and default enrichment are covered. The remaining gap is the duplicate-resolution path and the fact that no parameter is required, which leaves the agent guessing what to supply and what happens on a match.

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 goes further by framing domain and profile_url as alternative sources of identification and clarifying that the tags argument is additive to the customer's defaults. It does not address what happens if neither identifier is supplied, despite zero required 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?

States a specific verb and resource ('Add a company to the customer's connected CRM') plus the two accepted inputs, which cleanly separates it from siblings like add_person_to_crm, search_companies, and find_company_details. 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?

Usage is implied by the mutation verb and the note that it checks the CRM for the same domain first, which hints it handles dedupe itself. However, it never says when to prefer this over find_company_details + update_crm_record, or when a duplicate should be routed to confirm_possible_match instead. No explicit exclusions are given.

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

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

With annotations already declaring write, open-world, non-idempotent, and non-destructive behavior, the description adds substantial context: the operation runs in the background, returns a job id for get_bulk_add_status, skips existing people, and consumes one lookup credit per person for whom an e-mail is found.

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 dense sentences, front-loads the core action and scope, and includes only operational details that help an agent call the tool correctly.

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

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

An output schema exists, so return values need not be explained in detail. The description still covers the key operational facts an agent needs: limit, required profile_url provenance, background job id, duplicate skipping, and credit usage.

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 parameter documentation is already strong. The description adds meaningful semantics for profile_url provenance and refusal rules, the 100-person limit, and credit implications tied to email lookup, though it does not further explain tags, include_phone, or only_with_email 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 names a specific verb and resource ('Add up to 100 people to the customer's connected CRM'), states it runs in the background, and explicitly distinguishes this bulk tool from the single-person sibling add_person_to_crm.

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 clearly routes usage: profile_url must come from search_prospects or find_contact_details, other links are refused, and add_person_to_crm is named as the alternative for one person from any profile link. It also states that existing CRM people are skipped.

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

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

Goes well beyond the annotations by disclosing the deduplication check, the possible-match gating via add_anyway, the use of the customer's field settings and default tags, and credit consumption for e-mail lookups and phone discovery. This is rich behavioral context for 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?

Three tightly packed sentences: purpose first, then workflow and gating, then credit cost. Every sentence adds useful information without redundancy.

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

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

Given the output schema and annotations, the description covers the essential workflow, side effects, and cost. A minor gap is the lack of reference to the sibling confirm_possible_match for resolving flagged matches, but the add_anyway override is clearly explained.

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 eight parameters. The description adds light context about which fields drive the lookup and how add_anyway works, but does not meaningfully expand on parameter semantics 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?

States a specific verb and resource: 'Add a person to the customer's connected CRM.' It is clearly singular and distinguishable from add_company_to_crm, though it does not explicitly call out the bulk sibling add_people_to_crm.

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 explains the lookup sources and the duplicate-check behavior, but it never states when to prefer this tool over alternatives such as add_people_to_crm or find_person_in_crm. Usage is implied rather than explicitly guided.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses two behavioral facts the annotations cannot: the answer is refused unless it identifies the person, and confirming conditionally writes the profile link onto the record only when a prior search/lookup returned that link at the named company. That is exactly the kind of side-effect and failure-mode detail an agent needs before invoking a write 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?

Three sentences, front-loaded with the action and the source of the input, followed by the validation rule and the side effect. The final sentence is dense but every clause carries decision-relevant information; only minor tightening is possible.

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 annotations covering the safety and idempotency profile and an output schema covering return values, the description supplies the remaining pieces an agent needs: the prerequisite sibling, the refusal condition, and the conditional profile-link write. Nothing essential to calling 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 would be 3, but the description adds a cross-field rule not present in the schema: the answer must be anchored to the person via name, company, e-mail or profile link. It also clarifies how profile_url interacts with the conditional write, giving extra semantic value over the per-parameter 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 object ('Record the customer's answer about a possible match') and ties the resource directly to the sibling that produces it, find_person_in_crm. An agent can distinguish this from find_person_in_crm and update_crm_record 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 makes clear this is the follow-up step after find_person_in_crm yields a possible match and the customer has responded, and it states the precondition that the answer must identify the person. It doesn't explicitly name a when-not case or an alternative tool, keeping it 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.

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

Annotations already declare openWorldHint=true, idempotentHint=true and destructiveHint=false, so the description's job is to add cost and side-effect context — and it does: 'Uses one lookup credit when the details are not already stored' explains both the billing impact and the caching/storage behavior that justifies readOnlyHint=false. It stops short of stating what happens on a miss or a failed lookup.

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 capability and field list, followed by the cost caveat. No filler and nothing repeated from 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?

An output schema exists so return values need not be described, and annotations cover the safety profile. The credit note closes the main behavioral gap; what remains unstated is the zero-required-parameter edge case and whether either input is preferred, which is a modest omission for an enrichment 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% and both parameters are documented in the schema, so the baseline is 3. The phrase 'from its own domain or its public page link' mirrors the two params and signals they are alternatives, but adds no format, precedence, or fallback semantics beyond what the schema already says.

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 ('find') plus resource ('company's details') with an enumerated field list (industry, size, location, website, phone, technologies) and the two accepted input sources. It implicitly separates itself from search_companies and find_contact_details by being a detail-enrichment lookup rather than a search or person lookup, though no sibling is named outright.

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?

No statement of when to prefer this over search_companies or find_contact_details, and no guidance on choosing between domain and profile_url or what happens when neither is supplied (required parameters = 0). The only decision-relevant note is the credit cost, which is billing behavior rather than usage routing.

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

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

The annotations already declare openWorldHint, idempotentHint, destructiveHint, and readOnlyHint. The description adds a valuable behavioral detail not in annotations: it consumes one lookup credit only when an e-mail address is found. It does not cover all operational details such as rate limits or account requirements, but it goes beyond annotation coverage.

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

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

It is two sentences, front-loaded with the purpose and inputs, followed by the credit rule. Every sentence carries useful information, and there is no redundant restatement of the tool name.

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

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

Given the existing output schema and annotations, the description is complete enough for an agent to understand what the tool returns conceptually (contact details and job), how to invoke it, and its credit behavior. No critical context appears 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 description coverage is 100%, so all five parameters are already documented in the schema, including name+company pairing and include_phone's extra-credit behavior. The description reinforces the main input modes but adds no syntax, format, or constraint detail 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 a specific verb and resource ('Find a person's work e-mail address, other contact details and current job') and identifies the input modalities. This clearly distinguishes it from siblings such as find_company_details by being person-focused and from CRM record lookups by using public-profile/email/name-company lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear invocation context by naming the three lookup routes: public profile link, e-mail address, or name plus company. It does not explicitly say when to use this instead of alternatives like find_person_in_crm or search_prospects, so it lacks full alternative/exclusion guidance.

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

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

Annotations already declare this a read-only, idempotent, closed-world operation; the description adds genuinely new behavior: no lookup credit is consumed and name-only matches are reported as possible matches, not confirmations. That match-confidence rule is the key behavioral fact an agent needs and it is not in the annotations.

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

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

Two tight sentences with no filler; the core check is front-loaded, then the credit-cost and match-confidence caveat follow. Every clause carries 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers inputs, cost, and match-confidence semantics. Minor gap: it doesn't state what a no-match result implies (e.g., safe to add via add_person_to_crm) or whether e-mail matching is exact.

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%, including the 'required unless an e-mail is given' rule and the profile_url guidance, so the schema already carries the semantics. The description only restates the name-or-e-mail key and optional profile link, adding no format or precedence detail 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 (check/find) and resource (a person in the customer's connected CRM) plus the lookup keys used. It names confirm_possible_match as a follow-up but does not distinguish itself from other lookup siblings such as search_crm, find_contact_details, or find_company_details.

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 operating context: uses no lookup credit, can be keyed by name or e-mail, and a name-only hit must be treated as a possible match rather than proof. It also routes the agent to confirm_possible_match for the customer's answer. It stops short of explicitly saying when to prefer this tool over search_crm or find_contact_details.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally; the description adds genuine context by saying the response surfaces blockers that would prevent lookups or adds. It does not say whether credit counts are live or cached, or how stale the account state may be.

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, front-loaded with the resource and followed by the three returned facts. No preamble, no repetition of the title, nothing 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 an output schema present, the description need not enumerate return values, and it still names them at a high level. For a zero-parameter read tool the only real omission is sibling disambiguation from get_profile, which leaves the agent guessing which account/profile view to call.

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 takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing for the description to clarify. Baseline 4 applies for a parameterless tool.

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?

A specific verb ("Show") plus a specific resource ("the Add to CRM account this connection belongs to"), and the description enumerates the three things returned: connected CRM, remaining lookup credits, and current lookup/add blockers. It is clear on its own, but it never distinguishes itself from the sibling get_profile, which an agent could reasonably confuse it with.

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 — the mention of blockers "that will currently stop a lookup or an add" hints at a pre-flight check before calling add_* tools, but the description never says to call it before adding, or when to prefer it over get_profile. No alternatives or exclusions are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the job_id lineage and the result buckets, but since an output schema exists, the bucket enumeration largely restates what is already structured, and it says nothing about in-progress behavior or polling.

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, front-loaded with the action and resource, with the originating tool and result categories packed into the same clause. No filler or redundant 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 single-parameter, read-only status tool with an output schema and complete annotations, the description covers purpose, provenance of the ID, and the reported states. Only polling/retry guidance for an unfinished job is absent, which is a minor 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 the single parameter's schema description ('the job id returned by add_people_to_crm') already explains its origin. The description reinforces that provenance but adds no new format or lookup detail, so the 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 (check progress) and resource (a bulk add job), and names the originating sibling add_people_to_crm so the agent knows exactly which workflow it belongs to. It also enumerates the outcome categories reported (done, added, skipped, failed), leaving no ambiguity about what the tool returns.

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 phrase 'started with add_people_to_crm' gives clear triggering context: use this after kicking off that tool. There is no explicit exclusion or statement about what to do instead (e.g. polling cadence or what to do if the job is still running), so it falls 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.

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

Goes well beyond the readOnly/idempotent annotations with cost behavior (no lookup credit), fidelity semantics ('as the CRM holds it'), and an explicit prompt-injection guardrail that record text is data, not instruction. That injection warning is exactly the kind of behavioral context 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?

Three short sentences with zero padding; the core action is stated first, followed by cost, the update relationship, and the safety note in descending priority. Every sentence carries distinct 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?

With an output schema covering return values and full annotation coverage of the safety profile, the remaining gaps an agent needs — cost, fidelity, downstream mutation relationship, and injection safety — are all addressed. Nothing required 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 description coverage is 100%, with record_id, entity_type, and record_type all documented in-schema, so the baseline is 3. The description adds no further semantics about parameter interaction or defaults beyond what the schema already states.

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 ('Read one person or company record') plus the framing 'as the CRM holds it,' which distinguishes it from enrichment/summary tools. It names the related sibling update_crm_record, though it does not explicitly contrast with search_crm or find_person_in_crm, which also return record data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Uses no lookup credit' gives a real selection signal versus credit-consuming lookups, and 'update_crm_record changes only a record read this way' establishes a clear prerequisite workflow. It stops short of stating when to prefer this over siblings like find_contact_details or search_crm.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that — the opaque id's uniqueness scope and its stability across token refresh, reconnection and display-metadata changes — which supports caching decisions. It does not address behavior when credentials are missing or unauthenticated. It is worth noting the credits are 4 for parameter text; here the score reflects that no errors/auth semantics are described beyond what annotations supply.

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 purpose, then the identifier guarantees. Nothing is redundant or padding.

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

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

With zero params, rich annotations and an output schema, the description covers what it must: what is returned and the stability of the id. Only the authentication failure mode is unmentioned, which is a minor gap given the 'authenticated credentials' wording.

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 takes zero parameters, so the schema-completeness baseline of 4 applies. The description reinforces that no argument is needed by tying the result to the caller's credentials.

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 (return) and resource (the profile) with a clear scope: the identity bound to the current request's credentials. This implicitly separates it from id-based siblings such as get_account and get_crm_record, but it never names them, so differentiation is inferred 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?

The phrase 'this request's authenticated credentials' implies the tool is used to discover the caller's own identity and needs no arguments, which is useful context. However, there is no explicit when-to-use vs when-not guidance and no alternative sibling is named for the case where an id is already known.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful fact that ids are exposed per list, which is the key output for chaining into save_to_list; polite pagination/ordering details are absent but an output schema exists.

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

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

A single front-loaded sentence with no filler, covering what is shown and the identifier returned.

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, rich annotations, and an output schema, the description is largely sufficient. The only gap is the absence of any note tying it to save_to_list as the source of list ids.

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 takes zero parameters, so the baseline is 4; the description correctly signals a no-argument listing call with no filtering implied.

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 and resource ('Show the customer's saved lists of people and companies') and adds that each list's id is returned, which separates it from save_to_list. It doesn't explicitly name sibling alternatives, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus save_to_list or the search tools, and no mention that it is the prerequisite step for obtaining list ids before writing. Usage is only implied by the content.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful detail that this depends on an externally-resolved record ID, but says nothing about duplicate logging on retry (relevant given idempotentHint=false) or side effects on the CRM record.

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

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

Two sentences, no waste, with the action stated first and the prerequisite second. Nothing is padded or restated from 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?

An output schema exists and all parameters are fully described, so return values and field meanings are covered elsewhere. The description supplies the one thing structured fields cannot: the ID provenance requirement. Only the retry/duplication behavior for a non-idempotent write is left unaddressed.

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 every one of the nine parameters is already documented in the schema, including the type values and date formats. The description adds no semantics beyond that and so sits at the 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?

States a specific verb (log) and resource (note/call/meeting/task activity) and names the object it attaches to (person or company record in the customer's CRM). It implicitly separates itself from the lookup/add siblings it references, though it never distinguishes itself from update_crm_record, which is the nearest ambiguous alternative.

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 a hard prerequisite: the record must be one returned by find_person_in_crm, search_crm or add_person_to_crm, which tells the agent it must resolve an ID first. It stops short of stating when to choose this over update_crm_record or when not to log.

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

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

Adds real context beyond the annotations: no lookup credit is consumed, a nonexistent list name creates the list, and the operation does not push anything into the CRM. Annotations already declare idempotent/non-destructive/closed-world, so the residual gap (error behavior on invalid or stale profile_url) is minor.

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 core action and cap, then credit/creation semantics, then the scope boundary. 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?

Given an output schema and full annotation coverage, the description supplies everything an agent needs to choose it and call it correctly: prerequisites on input provenance, list-creation side effect, cost implications, and the list-vs-CRM distinction.

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 each parameter carries its own description, so the schema does the heavy lifting. The description mostly restates schema facts (100-item cap, auto-creation of list_name) rather than adding syntax or precedence rules such as what happens if both list_id and list_name are supplied.

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 (save) plus resource (people → a list), with quantity bound (up to 100) and the required source of the items (profile_url from search_prospects or find_contact_details). The final sentence explicitly separates it from the CRM siblings: 'it does not add them to the CRM.'

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?

Clear when-to-use context: only people returned by search_prospects/find_contact_details, and only when the goal is a list for later rather than a CRM write. It stops short of covering the list_id vs list_name choice or pointing to list_lists as the way to obtain list_id, which the schema does instead.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds a crucial behavioral detail not in annotations: credit consumption occurs for each page that has not been searched before, explaining why the operation is not purely read-only.

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 two sentences, front-loaded with the core purpose and filter dimensions, followed by return value, alternative, and cost behavior. Every clause carries useful information with no redundancy.

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

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

Given the output schema, annotations, and 100% schema description coverage, the description supplies everything an agent needs: what it searches, what it returns, when to use an alternative, and the credit cost. No critical gaps remain.

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 all parameters are already documented. The description restates the filter categories (name, keywords, location, headcount, domains) without adding syntax, format, or interaction details beyond what the schema provides; thus the baseline of 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?

The description states a specific verb (search) and resource (companies) and enumerates the filterable dimensions (name, keywords, location, headcount, domains). It also explicitly contrasts with the sibling find_company_details, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative find_company_details for retrieving more details about a domain, giving clear routing guidance. However, it does not address when to use this search over other siblings like search_prospects or search_crm, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely non-structured context: "Uses no lookup credit" (a cost/quota trait) and a summary of what is returned (id plus CRM link), which is exactly the kind of value-add expected above the annotation baseline.

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, zero filler, with the purpose front-loaded and the cost/quota note immediately after. Every clause carries information the agent can act on.

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 annotations covering safety, full schema coverage, and an output schema in place, the description only needs to frame purpose, cost, and return shape — all of which it does. The one gap is sibling disambiguation for a crowded set of search/find tools, which would materially help selection.

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 (kind, page, limit, query) are already documented in the schema. The description restates the query dimensions and the people/companies distinction without adding syntax, defaults, or paging behavior beyond what the schema already says, so the 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+resource ("search the customer's connected CRM") and enumerates the searchable fields (name, e-mail, company name), so the agent knows exactly what the tool does. It does not, however, distinguish itself from close siblings like search_companies or find_person_in_crm, leaving overlap ambiguous.

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 the use case (look up people or companies by partial name, e-mail, or company name) but never states when to prefer this over search_companies, find_person_in_crm, or search_prospects. No exclusions or prerequisites are given, so the agent must infer routing from sibling names.

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

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

Adds context beyond the annotations: it discloses the one-credit-per-unsearched-page cost model and explains the read/cache boundary that underlies idempotentHint=true. It does not describe result caps or what happens when a page repeats with different filters, so the disclosure is strong but not complete.

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 clauses: purpose and filters first, return shape second, cost model last. No filler and nothing 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?

With 11 optional parameters, an output schema and full schema coverage, the description only needs to cover return shape and cost, and it does both. The handoff to find_contact_details closes the main loop; minor gaps are pagination behavior across changed filters.

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 carries the enum vocabularies, ranges and per_page limits. The description only restates the filter families, adding no syntax or interaction guidance (e.g., how titles and keywords combine), 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?

Opens with a specific verb and resource ('Search for people to reach out to') and names the filter dimensions (title, department, seniority, location, company details). It also names the sibling it hands off contact lookup to, so an agent can distinguish it from find_contact_details and search_companies 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?

Clearly states the follow-up step: it returns a profile link but not contact details, which find_contact_details supplies. It gives no explicit exclusion for its closest sibling search_companies (people vs. companies), so the when-not guidance is only partially covered.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the description need not repeat that this is a mutation. It adds important behavioral context beyond annotations: a prior get_crm_record read is required, and only previously observed e-mail addresses and phone numbers can be removed. It does not explain partial-update semantics for omitted 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?

The description is two sentences with no wasted language. The primary update scope is front-loaded, and the prerequisite and removal constraint follow immediately.

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 a rich input schema, an output schema, and destructive annotations, the description provides the key operational context: read first and restrict removals to previously read values. A minor gap is that it does not state whether omitted fields remain unchanged during a partial update.

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 14 parameters, including person vs. company field applicability and removal constraints. The description adds grouping by person/company and the read-before-remove rule, but does not add parameter syntax or format details 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: change fields on a record in the customer's CRM. It enumerates person and company field scopes and clearly frames the operation as updating an existing record, distinguishing it from sibling add_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a strong prerequisite: the record must have been read with get_crm_record first. It also constrains removals to e-mail addresses and phone numbers shown by that read. It does not explicitly compare against alternatives such as add_person_to_crm or add_company_to_crm, but the update vs. create distinction is clear.

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