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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is covered. The description adds nothing beyond that profile — it does not say what happens on repeat calls, whether the transition is reversible, or what gets returned.

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 short sentence with the action and target state front-loaded and no wasted words. It is efficient, though so terse that it borders on under-specification rather than optimal brevity.

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 one-parameter mutation with full schema coverage and no output schema, this is minimally adequate. It omits the idempotent behavior and error conditions (e.g., nonexistent or already-completed task_id), which the agent would need for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents task_id (numeric, positive). The description adds no extra meaning, which is the expected baseline when the schema does the heavy lifting.

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 ("Mark") and resource ("task") plus the target state ("Completed"), so the action is unambiguous. It does not differentiate itself from related siblings such as create_task or search_tasks, but the core purpose is 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?

There is no guidance on when to use this versus alternatives, no prerequisites, and no note about what happens if the task is already completed. The agent must infer the usage context entirely.

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 disclose the full safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description is not obligated to restate mutation semantics. It adds the prerequisite that pipeline/stage IDs must be sourced externally, but says nothing about side effects, duplicate deals, or default status/stage assignment.

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, both load-bearing, with the core action front-loaded and the dependency guidance immediately after. 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 12-parameter creation tool with no output schema and low schema description coverage, the description is thin. It never states that 'name' is the only required field, does not address enum behavior for status/priority, and gives no indication of what the call returns (e.g., the new deal's ID) or how defaults are applied.

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 only 42% across 12 parameters, so the description must compensate more than it does. It partially does so by pointing to list_pipelines and get_account_info as sources for pipeline_id/pipeline_stage_id and assignee_id/primary_contact_id, but the remaining parameters (tags, status, priority, monetary_value, company_id) get no elaboration 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?

Specific verb+resource ('Create a new deal'), mapping cleanly to the create_opportunity name and distinguishing it from the read/update siblings (get_opportunity, update_opportunity). It stops short of explicitly contrasting itself with create_task or other create_* tools, so it is clear but not maximally differentiated.

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 concrete prerequisite tools and the data each supplies: list_pipelines for pipeline/stage IDs and get_account_info for user IDs. That is actionable routing guidance an agent can follow. It lacks any when-not-to-use or duplicate-handling guidance, which keeps it out of 5 territory.

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, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it doesn't mention required fields, whether reminders/assignments trigger notifications, or side effects of linking to other records.

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 efficient sentence with the core action front-loaded and the optional linking qualifier trailing. Nothing is wasted, though brevity here reflects under-specification rather than discipline.

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?

A 9-parameter mutation tool with 22% schema coverage, no output schema, and no annotations covering field-level behavior needs far more explanation. The description leaves the agent guessing about most inputs and about what the created task looks like on return.

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 only 22%, so the description must compensate, but it only gestures at the related_id/related_type pair (and even then lists four of five enum values). It says nothing about the required name, nor tags, details, due_date, priority, assignee_id or reminder_date.

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?

Clear verb+resource ('Create a task') plus the linking scope, so the agent knows what it produces. It does not differentiate from siblings like create_opportunity or search_tasks, and it omits 'project' from the list of linkable types even though the schema's related_type enum includes 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as search_tasks (to check for duplicates) or complete_task. The agent must infer usage purely from the verb.

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 and openWorldHint=true, so safety and external-reach are covered. The description adds 'Returns the full person record,' which is useful because no output schema exists, but omits not-found behavior (error vs empty result) and any auth or rate-limit 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?

Two short sentences with zero filler; the lookup scope is front-loaded and the return behavior follows immediately. Every clause 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 one-parameter, read-only lookup with annotations and no output schema, the description covers what it does, the exactness of the match, and the shape of the return. The remaining gap is the not-found/empty-result contract, which an agent would want before calling.

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 is a single required parameter with 0% schema description coverage, so the description must carry the meaning. It does add the important semantic that matching is EXACT (not partial), but says nothing about case sensitivity, whitespace trimming, or what happens with a non-matching address.

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 (look up) and a precise resource/scope (one contact by exact email address), which implicitly contrasts with the multi-result sibling search_people. It is clear and unambiguous, but it never names or explicitly contrasts with an alternative tool, so it stops short of the 5 tier.

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 phrase 'by exact email address' suggests this is the single-record lookup path when the email is known, versus a search tool. There is no explicit when-to-use statement, no exclusion (e.g. partial or fuzzy matching), and no routing to search_people.

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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful scope by saying it returns the account, the API user, and all users with their IDs, though it does not discuss result size or pagination for an all-users response.

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 short sentences, front-loaded with what is returned and followed by the key usage affordance for the returned IDs. There is 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 zero-argument lookup tool with no output schema, the description sufficiently names the returned entities and explains why the user IDs matter. It could be more complete by noting that the response lists all users, which may be large, but the core call behavior is clear.

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 there is no parameter ambiguity. The baseline for a zero-parameter tool is 4; the description correctly focuses on the returned entities rather than inventing parameter details.

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 three concrete resources: the Copper account, the API user, and all users with IDs. It is clear what the tool does, but it does not explicitly distinguish itself from sibling people-search tools like search_people or find_person_by_email.

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 useful downstream usage note: use the returned user IDs as assignee_id in other tools. However, it does not explicitly say when to use this tool versus alternatives such as search_people, nor does it state any exclusions or prerequisites.

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 and openWorldHint=true, so safety profile is covered. The description adds genuinely useful return-shape context (all fields plus custom fields) that no output schema provides, but says nothing about missing/invalid IDs, permissions, or field 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?

A single front-loaded sentence with zero filler; the scope qualifier (all fields, including custom fields) is attached directly to the verb-object rather than buried.

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 read tool whose annotations cover the safety profile, the description's note that custom fields are included largely compensates for the absent output schema. It falls short only on failure behavior and how to obtain a valid ID.

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% for the single required parameter and the schema already documents opportunity_id with type and exclusivity. The description adds no syntax, format, or ID-sourcing detail beyond the schema, 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 (Get) and resource (one deal) plus the return scope (all fields, including custom fields). The phrase 'one deal' implicitly separates it from sibling search_opportunities, but the description never names that sibling or explicitly contrasts them.

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 explicit when-to-use, when-not-to-use, or alternative named. 'One deal' weakly implies the caller already has an ID, but the agent must infer that from the required opportunity_id field rather than from the description.

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 and openWorldHint=true, so the safe-read profile is covered. The description adds one behavioral wrinkle – types=true flips the tool into listing activity types instead of activities – but that same fact is already documented in the schema, and nothing is said about pagination behavior or result shape.

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

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

Two sentences, no filler, and the primary listing behavior is front-loaded before the types=true special case. Appropriately sized for the tool, though the tail sentence could be tightened.

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 is the only place return shape could be described, and it says nothing about what an activity object looks like or how pagination fields relate. It covers the core modes adequately but leaves an agent guessing at output structure.

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 71%, so most parameters (since, until, page_size, page_number) are self-documented with format and bounds. The description only gestures at record scoping ('for a record'), without clarifying how parent_id and parent_type combine, which is the one underspecified pair left to both schema and 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?

States a specific verb (list) and resource (activity), enumerates the activity kinds (notes, emails, calls, meetings, stage changes), and covers both scoping modes (single record vs account-wide date range). It implicitly contrasts with the write-side sibling log_activity, but never names an alternative 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?

The description implies two usage modes – per-record or account-wide in a date range – which gives some context. However, it names no alternatives (e.g., log_activity for writing) and states no conditions or exclusions that would tell an agent when to pick this over a sibling search tool.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by indicating that results include pipeline stages and stage fields such as id, name, and win probability.

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 short sentences with no wasted text. The core action is front-loaded, and the usage note is compact and relevant.

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 list tool, the description gives enough context: what is returned at a high level and why it matters. It could be slightly more complete by clarifying the full return shape or naming the follow-up update tool, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so parameter semantics are not a concern. The schema is empty and the description appropriately does not invent parameter details.

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 ('List pipelines') and adds what is included ('with their stages'). It is clear what the tool does, though it does not explicitly differentiate itself from any sibling tool.

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 'Needed to move deals between stages' gives a clear usage context. It does not name alternatives or state when not to use the tool, but the intended scenario is explicit.

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 disclose this is a non-read-only, non-idempotent, non-destructive, open-world write, so the safety profile is covered. The description adds the default-type behavior but does not warn about duplicate creation (relevant given idempotentHint=false) or permission requirements.

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: the action and its default come first, then the companion-tool hint for IDs. Nothing is 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 five-parameter mutation tool with annotations and no output schema, the description covers the default behavior and the ID-discovery path. Missing only the meaning of parent_id and any return/confirmation detail, which keeps it short of fully 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 60%, and the description's additions (note is the default, activity_type_id comes from list_activities) largely restate what the schema already says ("default 0 = Note"). It never explains what parent_id refers to or how parent_type interacts with it, so the coverage gap is only partly compensated.

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 ("Add") and resource (note or user activity type) and enumerates the parent entities it attaches to (person, company, lead, opportunity). It is immediately distinguishable from read-side siblings like list_activities and from create_task.

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 routing guidance for one key decision: call list_activities with types=true to obtain activity_type_id values. It does not, however, clarify when to log an activity versus using create_task, or any prerequisites/restrictions on logging.

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 and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no mention of result ordering defaults, whether filters combine with AND/OR, or what an unfiltered call 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?

A single front-loaded sentence with no filler. It is arguably too terse for a 9-parameter tool, but nothing in it is wasted.

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 9 optional parameters, no output schema, and an undocumented sort_by, the description leaves an agent unable to determine default result size, default ordering, or what happens with no criteria. For a search entry point it should say more.

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 only 33%, but the description does map natural-language concepts to parameters (assignee → assignee_ids, location → city/country, tags → tags), which helps. It says nothing about sort_by, sort_direction, or pagination behavior, and sort_by in particular is undocumented in both schema and 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?

Names a specific verb (search) and resource (companies) and enumerates the searchable axes (name, tags, assignee, location). Sibling tools like search_people and search_opportunities are implicitly distinguished by the resource noun, but the description never states the distinction 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?

There is no statement of when to use this tool versus the sibling search tools, no mention that all parameters are optional and an empty query returns everything, and 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.

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral value by disclosing the return shape: totals by status and stage (count and value) plus a compact list with stage names substituted for IDs. It omits pagination behavior and what 'raw' changes.

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 searchable dimensions, followed by return shape and use case. The field enumeration is slightly list-like but each item carries real filtering 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 an 18-parameter, zero-required search tool with no output schema, the description covers the key filters and the return contract well, and annotations handle the safety profile. Gaps are minor: the opaque 'raw' flag, sorting, and pagination controls are not addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% and the description mostly restates fields already documented in the schema. It does add useful intent-level mapping ('value' to monetary value, 'owner' to assignee), but leaves undocumented params (raw, tags, sort_by, sort_direction) unexplained in either place.

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 ('Search deals') and enumerates the searchable dimensions (name, status, pipeline, stage, owner, company, value, close date). It also distinguishes itself from the singular get_opportunity sibling by describing a filtered list with aggregate totals.

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 usage context ('Good for pipeline reviews and forecasts'), which tells the agent when this tool is the right call. It does not name alternatives or exclusions (e.g. when to prefer get_opportunity for a single deal), so it stops short of full routing 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it "Returns a compact list," which hints at a trimmed response format (relevant given the `raw` flag), but it says nothing about pagination behavior, result limits, or match semantics.

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 purpose is front-loaded before the return-format note. 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?

For a 14-parameter tool with no output schema, the description is thin: it never explains pagination defaults, sort behavior, or the `raw` toggle, and gives no usage routing against siblings. The "compact list" note is the only return-value context provided.

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 14 parameters and only 64% schema description coverage, several params (city, phone_number, tags) have no schema description, and the description partially compensates by naming which fields are searchable. It omits pagination, sorting, `raw`, and `not_contacted_since` semantics, so it adds modest value over 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 ("Search") and resource ("contacts (people)"), and enumerates the searchable dimensions (name, email, company, tags, assignee, location), so the agent knows exactly what this tool does. It does not, however, contrast itself with the closely related sibling find_person_by_email.

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 explicit when-to-use or when-not-to-use guidance. The overlap with find_person_by_email is left unaddressed, so an agent has no stated rule for choosing between a broad search and a targeted lookup.

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 and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that – no pagination defaults, result limits, sort behavior, or auth requirements – leaving the extra context the annotations don't cover undisclosed.

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 compact sentence naming the filters plus a short illustrative example. Zero waste, front-loaded with the core capability, and every clause 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 9-parameter read-only tool with no output schema and no annotations about returns, the description covers the searchable dimensions but omits pagination behavior (default 20, max 200) and sorting guidance. Adequate, but an agent must open the schema for anything beyond the high-level purpose.

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 78%, so the schema does most of the work; baseline is 3. The description maps four concepts (owner, status, due date, related deal) onto assignee_ids, statuses, due_before/after, and opportunity_ids, which adds modest conceptual framing but no syntax or format 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 (Search) and resource (tasks) plus the filterable dimensions (owner, status, due date, related deal). It is clearly distinguishable from write siblings like create_task and complete_task, though it does not explicitly name a sibling search tool to differentiate from.

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 quoted example "what's overdue for me?" implies the intended use case (filtering by assignee plus due date), which is helpful context. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives, so usage is only implied.

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 phrase 'Only the fields you pass are changed' is a powerful behavioral disclosure that describes the partial update nature of the function. This is a crucial operational detail that is not covered by the idempotent or destructive hints 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?

The definition is extremely concise, fitting all vital functional information into a single, dense sentence. There is zero waste of language.

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

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

The description is highly complete from a calling perspective because it defines the update behavior. A deduction is made only because there is no output schema, and the description does not address what the successful return value might look like.

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 only 50% schema description coverage, the description compensates well by listing many functional actions (e.g., 'move it to another stage,' 'mark it Won/Lost'). This adds necessary semantic meaning to the parameters beyond what the schema alone 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 ('Update') and identifies the resource ('deal'). It clearly details the specific actions the tool performs, such as moving stages, marking Won/Lost, or changing owner/value, immediately clarifying its scope relative to sibling tools like create_opportunity.

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?

While it does not explicitly name alternatives, the critical guideline 'Only the fields you pass are changed' provides essential context on *how* the tool should be used (partial update), which dictates when it is appropriate versus needing a full replacement.

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