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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the mutation nature is largely established. The description adds author-resolution context and that the note goes to the deal timeline, but doesn't clarify whether the operation is additive/non-destructive beyond what annotations state, nor what happens on partial failure. It adds a moderate amount beyond structured data without contradiction.

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 tight and efficient — roughly three sentences covering purpose, author options, and a concrete usage example. Every sentence earns its place; no filler or redundancy.

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

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

For a 4-parameter tool with 100% schema coverage and explicit annotations, the description adds the key missing context: author resolution semantics and a practical use-case example. It does not explain return values, but with no output schema and a simple mutate operation, that's a minor gap. Fairly complete for the tool's complexity.

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

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

Schema description coverage is 100%, with each param (text, user, deal_id, user_id) documented in the schema itself. The description adds the author-resolution logic (priority order, single-user omission), which is genuinely non-obvious value. However, most parameter meaning is already carried by the schema, 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?

The description specifies the exact verb ('Add a text note/annotation to a deal's timeline') and resource (deal timeline). It is clearly distinct from sibling tools like list/create/update/close deal or task tools — none of which describe adding timeline notes. The scope is precise and immediately actionable.

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

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

The description explicitly states author resolution rules (by user_id, by email/name in 'user', or omitted when single-user account) and provides an explicit 'Use when:' example with a concrete phrase. This gives clear guidance on when to invoke and how author parameters should be chosen, exceeding minimal expectations.

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 and destructiveHint=false, implying mutation without destruction. The description adds the context that lost_reason names are resolved against account-configured reasons, which is useful. However, it doesn't disclose what happens to open pipeline stages, whether closing is irreversible, or what the closed deal's resulting state looks like. With no destructiveHint and reasonable annotation coverage, this is adequate but not rich.

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

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

The description is compact—two sentences covering purpose and usage, plus example phrases. It's front-loaded with the core action and efficiently conveys the lost-reason workflow. Slight inefficiency exists in the redundant phrasing around lost_reason/lost_reason_id, which could be tightened, but overall it earns its space.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the essential custom logic (lost-reason resolution and optional note). It handles the two dynamic params well. However, it doesn't explain what result the tool returns (e.g., closed deal object, confirmation), what validation occurs on lost_reason names, or preconditions like whether the deal must be in an open state to be closed.

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 covers all 5 parameters at 100%, so baseline is 3. The description adds value by clarifying the relationship between lost_reason (by name) and lost_reason_id (by ID), and how names are resolved. It also ties the note parameter to why the deal was lost. This exceeds the baseline by explaining semantics beyond simple field labels.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Mark a deal as won or lost.' It identifies the specific verb+resource (close/update deal status) and distinguishes the tool's purpose from siblings like rdcrm_update_deal and rdcrm_create_deal by focusing on the win/loss outcome state. The field guidance for lost deals adds specificity.

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 provides concrete example phrases ('mark the Acme deal as won', 'we lost the Beta deal because of price') that signal when to invoke this tool. It also explains the lost-reason resolution mechanics (names vs IDs against account-configured reasons). However, it doesn't explicitly state when NOT to use this tool or name alternative tools (e.g., rdcrm_update_deal) for other deal modifications.

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 correctly declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, matching the create operation. The description adds value beyond annotations by explaining automatic name resolution ('names are resolved automatically'), the stage-by-ID-or-name flexibility, and optional fields. It doesn't mention potential side effects like duplicate-creation behavior, but the openWorldHint and non-destructive annotations align with the described behavior.

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

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

The description is compact and well-organized: a sentence declaring purpose, a sentence listing optional fields grouped logically, and a concrete usage example. Zero wasted words, all information is useful for tool selection and invocation.

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 tool's moderate complexity (11 params, no output schema), the description covers the creation flow, parameter resolution strategy, and gives a worked example. It could mention return value format (no output schema), but the description is largely complete for a create operation where the caller likely cares about success/failure and the created deal's ID. Annotations cover the behavioral side.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters. The description adds value by explaining the resolution logic for stage_name (with pipeline_name to disambiguate), user (by email/name), and clarifying relationships between parameters (e.g., contact_name required if contact_email is new). This goes beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: 'Create a deal in a pipeline stage.' It specifies the verb (create), resource (RD Station CRM deal), and location (pipeline stage). It distinguishes from siblings by making clear it's the creation tool (vs rdcrm_update_deal, rdcrm_get_deal, rdcrm_close_deal).

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 provides a clear usage example ('create a deal for Acme in the Qualification stage worth R$5000') and explains when to use it. However, it doesn't explicitly state when NOT to use it or name alternatives for edge cases (e.g., when to update vs create). The example context makes usage reasonably clear.

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 provide readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable context beyond annotations: mentions the 403 error on paid plan types for free accounts and explains assignee resolution behavior. It doesn't describe what happens if assignee is required but not provided on multi-user accounts or the response format, but since there's no output schema, some gaps remain.

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 efficiently organized into two compact paragraphs plus a usage example. Every sentence carries information - the free-plan caveat, assignee resolution, and the when-to-use example are all distinct and relevant. Slightly verbose in the param enumeration at the start, but overall tight.

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 create tool with 8 params, 100% schema coverage, and no output schema, the description covers the critical operational caveats (free-plan 403, assignee resolution, default type/hour). It doesn't explicitly describe the response/confirmation behavior, but for a non-destructive create operation the practical gaps are minor given strong schema coverage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining assignee resolution semantics that the schema doesn't capture (user vs user_id vs omitted, single-user account auto-resolution). It also clarifies that type 'task' is the only free-plan option. The notes about assignee disambiguation go beyond the 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 clearly states the verb ('Create a task on a deal'), the resource (deal tasks), and enumerates the key fields (subject, type, due date/time, assignee). It distinguishes itself from siblings by being the creation tool for tasks within deals, contrasted with rdcrm_list_tasks and rdcrm_add_note.

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?

Provides explicit when-to-use guidance with a concrete natural-language example ('schedule a follow-up call on the Acme deal for Friday 10am'). It also discloses meaningful constraints: free-plan accounts only allow 'task' type, and assignee resolution rules (user_id, user by email/name, or omitted for single-user accounts). This is strong exclusion/guidance native language.

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 agent knows this is a safe read operation with potential for new info. The description adds value by enumerating exactly what fields/data the response contains (emails, phones, title, notes, linked deals with status), which is useful behavioral context beyond the annotations. However, it doesn't disclose response format, pagination/limits for the deals list, or behavior when the contact doesn't exist.

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 waste. The first sentence states the purpose and enumerates return data efficiently; the second provides a crucial prerequisite. Perfectly proportioned for a focused single-ID retrieval tool.

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 read tool with strong annotations (readOnlyHint, openWorldHint) and full schema coverage, the description is nearly complete. It clearly states the purpose, return contents, and prerequisite. The only minor gap is not describing error behavior (e.g., non-existent contact) and not specifying the format of the returned deals. But given the tool's simplicity, this is adequate.

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

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

Schema description coverage is 100% and the single parameter contact_id already has a description noting its origin ('from rdcrm_search_contacts'). The description reinforces this cross-reference by stating 'Get the contact ID from rdcrm_search_contacts first.' While it doesn't add much beyond the schema, the parameter is simple (a plain ID string) and adequately documented. The description adds modest value on top of full schema coverage.

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 specifies the exact purpose: 'Get full details of one contact by ID' and enumerates the specific fields returned (emails, phones, title, notes, linked deals with status). It clearly distinguishes from sibling tools like rdcrm_get_deal (which fetches deals, not contacts) and rdcrm_search_contacts (which searches/list, not retrieves a full single record).

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

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

Explicitly states the prerequisite: 'Get the contact ID from rdcrm_search_contacts first.' This clearly instructs when/how to use this tool versus alternatives — you must first search to obtain the ID, implying this is a follow-up retrieval after discovery. This is excellent usage 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 agent knows this is a safe read operation. The description adds value by enumerating the specific fields returned (status, stage, value, owner, rating, dates, contacts with email/phone, products) which is useful behavioral context beyond the annotations. However, it doesn't describe response format details like pagination, nested structures, or failure behavior, which with openWorldHint could matter. With annotations covering the safety profile, a 3 is appropriate.

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?

Single sentence, front-loaded with the core action ('Get full details of one deal by ID') and efficiently enumerates the returned fields. Zero waste, every word 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 single-deal GET tool with one parameter (100% schema coverage), read-only annotations, and no output schema, the description provides the key completeness elements: what it does, scope (one deal), and what fields you get back. It lacks a mention of error/not-found behavior, and the absence of an output schema means the field list in the description partially compensates. Given the low complexity, this is adequately complete.

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

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

Schema description coverage is 100%, so the deal_id parameter is already documented in the schema with its own description. The description adds marginal value by noting deal_id comes from rdcrm_list_deals or rdcrm_get_contact, offering provenance context. There is only one parameter, and no enums or nested objects. The baseline of 3 applies since the schema does the heavy lifting, and the description adds modest extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get full details of one deal by ID' with a specific verb ('get'), resource ('deal'), and identifier ('by ID'). It lists the exact fields returned (status, stage, value, owner, rating, dates, contacts, products), distinguishing it from sibling tools like rdcrm_list_deals which retrieves multiple deals.

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 clearly conveys this is for retrieving a single full deal by ID, which differentiates it from rdcrm_list_deals (multiple deals). It does not explicitly state when NOT to use it or name alternatives, but the singular 'one deal by ID' phrasing provides clear context. The deal_id param also references sourcing from rdcrm_list_deals or rdcrm_get_contact, giving useful workflow context.

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 useful behavioral detail: default status 'open', sorting by most recent first, and that it returns one line per deal. However, it doesn't disclose pagination behavior or field/return format beyond the return summary.

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, information-dense blocks: filters+sorting, return format summary, and usage examples. Compact and well-structured. Minor redundancy: the default status 'open' appears twice (in the filter sentence and in examples), but overall clean and front-loaded.

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

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

With zero required params, an openWorld read tool, and a 100%-covered schema, the description is nearly complete. It covers filters, defaults, sorting, return format, and when to use. The only gap is no explicit depth on pagination limits beyond what the schema provides, but this is minor.

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

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

Schema coverage is 100% — every one of the 9 parameters has a clear schema description. The tool description adds a default ('open') reiterated in the schema, and the date-format (YYYY-MM-DD) that matches the schema descriptions. Baseline 3 is appropriate since the schema already carries 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+resource ('List deals') with clear filters enumerated (status, pipeline, stage, owner, name, date range) and sorting behavior. It clearly distinguishes from siblings by explicitly pointing to rdcrm_get_deal for full details and highlighting this is the list operation.

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?

Provides clear when-to-use examples ('what deals are open?', 'deals lost this month', 'show João's pipeline'). It distinguishes from rdcrm_get_deal (full details) but doesn't explicitly exclude alternatives like rdcrm_pipeline_overview, so it misses the 'when not to use' dimension.

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, so the read-only safety profile is covered by structured data. The description adds the flat one-line-per-task output format which is genuinely useful behavioral context beyond the schema. It doesn't specify pagination behavior or the total count semantics, but the annotations carry the main safety burden.

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

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

The description is compact and front-loaded: first sentence lists filters, second sentence gives the return shape, third provides use-case triggers. Zero wasted words, every sentence earns its place.

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

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

For a filtered-list read tool with 100% schema coverage, readOnlyHint=true, and no output schema, the description is appropriately complete. It covers what the tool does, what it returns, and when to use it. The only minor gap is no mention of what happens when no tasks match (empty result behavior), but this is a low-stakes list operation.

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 8 parameters are already well-documented in the input schema (each has a description and most have defaults/enums). The description adds marginal value by summarizing the filters collectively but doesn't add format or example details beyond what the schema provides. The due_after/due_before date format (YYYY-MM-DD) is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource ('List tasks') and immediately lists the full set of filter dimensions (deal, assignee, status, type, due date). The return format is clearly described ('one line per task: status, subject, id, type, due date, assignee, deal'), which distinguishes it from sibling deal/contact list tools like rdcrm_list_deals.

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 reference phrases ('what are my pending tasks?', 'overdue follow-ups this week') provide concrete usage context. However, there are no explicit exclusions or comparisons against alternative tools (e.g., when to use create_task vs list_tasks is obvious, but no when-not guidance is given). The natural-language triggers serve as good 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?

Discloses defaults (30-day window, 14-day stall threshold), the funnel-order output, and the error behavior ('errors list all options' when pipeline needs disambiguation). Annotations already mark it readOnly (safe read) and openWorld (account state can change), and the description adds contextual depth without contradicting 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?

Three tight paragraphs: what it returns, plus what it's best for, plus quick use-case prompts. Zero wasted words; front-loaded with the core functionality and defaults. Very efficient.

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

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

For a read-only report tool with no output schema, it describes return contents, defaults, disambiguation behavior, and typical user intent. The one minor gap is that it doesn't describe return format/structure fields, but for an aggregate report the narrative coverage is strong. No output schema means description must carry some burden, which it does reasonably well.

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% — all three parameters have descriptions in the JSON schema itself (stalled_days, pipeline_name, closed_period_days). The description adds context like defaults for the window and stalled period, but these largely mirror the schema's default values. Baseline 3 is appropriate since the schema already carries the semantic weight.

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: 'Aggregated health report of a sales pipeline' with detailed breakdown of exactly what it returns (open deal count/value per stage, won/lost counts, win rate, stalled deals). Clearly distinguishes itself from siblings like list_deals (which lists individual deals) by being an aggregate health report.

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?

Provides explicit use cases ('how's my pipeline?', 'where are deals stuck?', 'sales summary for this month') and a clear when-to-use directive: 'fastest way to discover the account's pipelines and stage names/IDs'. This effectively orients agents on when to choose this over deal-level siblings.

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 description discloses the output format ('one line per contact: name, id, primary email, primary phone, job title') and explains how the returned id flows into rdcrm_get_contact for full details. While readOnlyHint is already declared in annotations, the description adds value by explaining the line-per-contact output structure and the linking behavior with deals. It doesn't cover pagination behavior details, but the annotations already cover the safety profile.

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

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

The description is compact and front-loaded: a single clear sentence stating the purpose, followed by an output-format sentence and two concise usage guidance sentences. Every line earns its place with zero waste or redundancy.

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

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

For a read-only search tool with 100% schema coverage, five well-documented optional parameters, and clear output-format disclosure, the description is largely complete. It also gives the usage context and alternative-tool pointers. Minor gap: pagination semantics (page/limit interplay) aren't explained in the description, though schema covers the parameters themselves. No output schema exists to offload return-value explanation, but the in-description line format compensates.

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 5 parameters are documented in the schema. The description adds marginal value by mapping query to partial-name and email/phone to exact-match, which reinforces the schema descriptions but doesn't add meaningfully beyond them. The baseline 3 is appropriate given full schema coverage 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+resource ('Search contacts in RD Station CRM') and explicitly defines the search semantics ('by partial name, exact email or exact phone'). It clearly distinguishes itself from siblings by noting the use of the returned id with rdcrm_get_contact, differentiating the search-and-list function from the full-detail and upsert operations.

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 provides explicit 'Use when:' guidance with concrete examples ('find Maria's contact', 'do we have someone with email x@y.com?') and explicit 'Don't use when:' exclusions pointing to an alternative tool (rdcrm_upsert_contact for create/edit). This meets the highest bar for usage differentiation.

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 only declare non-readOnly (mutation) and non-destructive, which the description aligns with by describing mutations. The description adds useful operational context like stage-by-ID-or-name flexibility and pause/resume semantics. With good annotation coverage, the burden is lower, and the description adds genuine context beyond 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 compact sentences plus a two-line usage block. Every sentence earns its place: scope enumeration, when-to-use, and when-not-to. Zero filler or redundancy.

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

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

Given 10 parameters, no output schema, and non-readOnly annotation, the description covers the main behavior patterns well. It doesn't explain return values, but no output schema exists and the tool is a standard update that likely returns the deal or success. Slightly more could be said about what happens on invalid interactions, but overall complete for the tool's complexity.

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

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

Schema coverage is 100%, so per rubric baseline is 3. The description adds value by clarifying the fluidity between stage_id and stage_name (with pipeline_name to disambiguate), and the hold boolean semantics (true pauses, false resumes), plus prediction_date explicit format (YYYY-MM-DD). This supplements the schema meaningfully.

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: 'Update a deal' with specific enumerations of what can be updated (stage, owner, name, rating, expected close date, pause/resume). Strongly distinguishes from sibling rdcrm_close_deal which handles won/lost outcomes, and from create/get which handle other lifecycle stages.

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

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

Explicitly provides when-to-use examples ('move the Acme deal to Negotiation', 'assign this deal to Maria') and an explicit don't-use exclusion that names the alternative tool (rdcrm_close_deal for win/loss). This is exemplary usage 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=false, idempotentHint=true, and destructiveHint=false, so the mutation and idempotency are covered structurally. The description adds value by explaining the upsert semantics (match by exact email before creating) and that it returns the contact id. It could go further by noting whether existing fields are overwritten or merged, but the core behavioral traits are well disclosed.

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

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

The description is compact, front-loaded with the core upsert behavior in the first sentence, and every sentence earns its place. The usage-example phrases are brief and concrete. No filler or redundancy.

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

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

For a 5-param flat tool with 100% schema coverage, required fields stated, idempotency and non-destructiveness declared via annotations, and no output schema expected (though it mentions returning contact id), the description is largely complete. It might benefit from noting partial-update semantics regarding omitted optional fields, but overall it's sufficient for effective agent 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?

Schema coverage is 100%, so all 5 parameters are described in the schema. The description adds useful supplementary semantics by clarifying that email is the matching key for upsert behavior, and that phone/title/notes are the optional fields being updated. It reinforces the required email+name constraint. A small gap: it doesn't clarify how the update interacts with omitted optional fields (whether they're preserved or cleared).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (create or update), resource (RD Station CRM contact), and the matching criteria (exact email). It distinguishes itself from siblings like rdcrm_search_contacts and rdcrm_get_contact by being the mutation/upsert tool, and explicitly mentions it returns the contact id.

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

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

The description provides clear when-to-use guidance with concrete examples ("add João to the CRM", "update Maria's phone"). It also explicitly states requirements (at least email and name) and notes which fields are optional, giving the agent a clear decision framework for invoking this tool.

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