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

With no annotations, the description should disclose behavioral traits. It does not mention idempotency, side effects, authorization requirements, or what happens if the product is already linked. The description provides zero behavioral context.

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

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

The description is a single concise sentence that conveys the core purpose. It is front-loaded and efficient, though it could benefit from additional context without becoming verbose.

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 has 5 parameters (3 required) and no output schema, the description is too minimal. It fails to explain return values, error conditions, or usage patterns, making it incomplete for an agent to fully understand the tool's behavior.

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% with descriptions for all parameters. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description clearly states the action (vincula) and objects (produto, negócio). Tool name reinforces purpose. No explicit differentiation from sibling tools, but no sibling performs the same operation, so it's sufficiently 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?

No guidance on when to use this tool versus alternatives, no exclusions or prerequisites. The context is implied by the tool name, but explicit guidance is missing.

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 no annotations, the description fully carries the behavioral burden. It discloses name/alias resolution, automatic timezone conversion to UTC, and pending activity checking before creation. This is good, though it omits details like auth requirements or response 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 three concise sentences with no filler. It is front-loaded with the main action and adds key details efficiently.

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, 2 required, no output schema, the description covers creation behavior, name resolution, timezone handling, and pending check logic. It does not describe success return, but overall it is adequately complete for a creation 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 coverage is 100%, so baseline is 3. The description adds some meaning (e.g., 'resolve automaticamente' for type and user_id, timezone conversion for due_time), but much of this is also in the schema descriptions. Minimal added value beyond 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 clearly states 'Cria uma nova atividade/tarefa no Pipedrive', specifying the verb (create) and resource (activity/task). It also mentions features like name/alias resolution and timezone conversion, distinguishing it from siblings like 'update_activity' or 'list_activities'.

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 some context: it checks pending activities when deal_id or person_id is provided, and mentions the force parameter to bypass. However, it does not explicitly state when to use this tool over other creation or activity-related tools, nor does it give when-not-to-use 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?

No annotations are provided, so description carries full burden. It discloses that the tool checks for open deals and that the force parameter overrides this only after user confirmation. However, lacks details on authorization or rate limits.

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 in Portuguese, front-loaded with purpose. Each sentence provides essential context. Could be slightly more structured but overall 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?

Given 10 parameters, no output schema, and no annotations, the description covers key aspects: prerequisite (existing entity IDs), alternative tool, input flexibility, and the open deal check. Lacks info on return value but that's acceptable without output schema.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining that pipeline_id, stage_id, and user_id accept either names or IDs. Also hints at force parameter behavior with 'Verifica deals abertos'.

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?

Description clearly states the tool creates deals only when person and organization already exist with known IDs, and explicitly distinguishes from create_deal_full for new leads. The verb 'Cria' and resource 'negócio' are specific.

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 (existing IDs) and when-not-to-use (new leads prefer create_deal_full). Also mentions flexibility in parameter input (name or ID) and the open deal check behavior.

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 no annotations provided, the description adds significant behavioral context: it creates multiple entities, auto-searches duplicates, propagates 'origem' to person (once, never changes), and accepts name or ID for pipeline/stage/user. However, it omits details like duplicate handling (skip/merge/error), response format, and idempotency.

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

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

The description is a concise paragraph of 4-5 sentences in Portuguese, front-loaded with purpose. Every sentence adds value: creation scope, duplicate search, origin propagation, name/ID acceptance, and usage guidance. No redundancy or fluff.

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 complexity (13 params, creates multiple entities, no output schema, no annotations), the description covers core purpose and usage but misses key completeness: no explanation of duplicate resolution, no confirmation of what the tool returns or errors, and no permissions or prerequisites. Adequate but with clear gaps.

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% with descriptions for all 13 parameters. The description adds minimal new semantic info; it mentions 'aceita nome ou ID' for pipeline, stage, and user, but schema already includes that. The propagation of 'origem' is behavioral, not semantic. Baseline 3 is appropriate as the description doesn't significantly enhance parameter understanding 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 clearly states this tool creates a complete deal in one call, including person, organization, deal, and activities. It explicitly says 'PREFERENCIAL para criar novos deals' and distinguishes from sibling tools like create_deal, create_person, etc., by covering multiple entities.

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

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

The description explicitly says 'Sempre usar este tool ao registrar um novo lead/oportunidade', giving clear context for when to use. It also implies this is the preferred method over simpler creation tools. However, it lacks explicit exclusion of cases where only a person or deal is needed.

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?

No annotations are provided, so the description must convey behavioral traits. It only states it creates a note with HTML support, omitting details like permissions, idempotency, error handling, or behavior when multiple parent IDs are specified.

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

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

The description is a single sentence that is concise and front-loaded with the main action. It could be slightly more structured but is efficient with no wasted words.

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 should explain what the tool returns (e.g., the created note's ID) but does not. It also lacks information about required permissions, validation rules, or how multiple parent IDs interact. The description is adequate for a simple tool but incomplete for production use.

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% with descriptions for all 4 parameters. The description adds context that the note can be associated with business, contact, or organization, but this is already clear from parameter names and schema descriptions. It does not add significant new meaning 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 clearly states it creates a note in a deal, contact, or organization, and that content supports HTML. This verb-resource combination is distinct from sibling tools like create_activity or create_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?

No explicit guidance on when to use this tool versus alternatives. The purpose implies it's for creating notes, but there are no when-to-use or when-not-to-use instructions.

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?

No annotations are provided, so the description carries the full burden. It discloses automatic duplicate checking but does not specify what happens when a duplicate is found (e.g., returns existing, errors, or is overridden by force parameter). Lacks details on permissions or return behavior.

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

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

The description is a single sentence that efficiently conveys purpose, usage alternative, and key behavior. No extraneous 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?

Given no output schema, the description could hint at what is returned (e.g., created organization ID). It covers purpose, usage, and duplicate checking, but missing return value information. Overall, it is fairly complete for a creation 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 coverage is 100%, but the description adds context beyond the schema by explaining the duplicate-checking behavior that relates to the 'force' parameter. The description also implies the tool is for standalone organization creation, adding semantic value.

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

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

The description clearly states 'Cria organização isolada' (creates isolated organization) and distinguishes from the sibling create_deal_full, which creates an organization together with a deal. This provides specific verb, resource, and scope differentiation.

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

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

Explicit guidance: for new leads, prefer create_deal_full; use this tool for isolated organization creation. Also mentions automatic duplicate checking, informing appropriate usage conditions.

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?

No annotations are provided, so the description carries the full burden. It transparently discloses the automatic duplicate check, warning behavior, and force flag usage. It also notes a prerequisite for custom_fields (run sync_person_fields first). Missing details on authentication, rate limits, or success response, but core behavior is well covered.

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 minimal: two sentences that efficiently convey purpose and key behavior. It includes an important note (IMPORTANTE) to emphasize the duplicate detection. No extraneous content.

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 7 parameters, no output schema, and no annotations, the description covers the duplicate detection nuance and force usage, but fails to specify the return value (e.g., created person object or ID) or error behavior. This is a notable gap for a creation tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the duplicate detection logic affecting email and phone parameters, and explicitly documents the force parameter's usage. It provides examples for owner_id and custom_fields, enhancing meaning 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 clearly states 'Cria um novo contato no Pipedrive', specifying the verb (create) and resource (contact/person). It also differentiates itself by highlighting the automatic duplicate detection, distinguishing from siblings like update_person.

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 usage guidelines by explaining the automatic duplicate search and the behavior when a duplicate is found. It also instructs on the force parameter: 'Use SOMENTE após confirmação explícita do usuário.' However, it does not explicitly contrast with alternative tools or state when not to use it.

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?

No annotations are provided, so the description carries the full burden. It states the tool returns data but does not disclose any behavioral aspects beyond that, such as authentication requirements, rate limits, or whether custom fields are always included. For a simple read tool, minimal transparency is acceptable, but some additional context would improve the score.

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 consists of two short sentences. The first sentence states the primary purpose clearly, and the second sentence provides an alternative and context. Every sentence is valuable and efficient, with no wasted words.

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 adequate for a simple read tool with one parameter. However, since there is no output schema, it could mention that the response includes both standard fields and custom fields. The mention of the summary tool partially compensates, but slightly more detail about what 'dados e campos personalizados' entails would make it 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?

The schema has 100% coverage for the single parameter deal_id, with a description 'ID do negócio'. The tool's description does not add any further meaning beyond what the schema already provides. Therefore, baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns data and custom fields of a deal. It distinguishes from the sibling tool get_deal_summary by noting that for a complete analysis including activities, notes, person, and history, the summary tool is preferred.

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 tells when to use this tool (for basic data and custom fields) and when to use the alternative get_deal_summary (for complete analysis). This provides clear 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?

With no annotations, the description carries the burden but only mentions the content of the history (status, stage, loss reason) without detailing behavioral traits like rate limits or auth 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 concise sentences with no redundancy; directly states purpose and provides alternative guidance.

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

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

For a simple tool with 3 parameters and no output schema, the description covers the essential purpose and usage distinction, though output format details are absent but not mandatory.

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 parameters. The description adds no new meaning beyond implying the history includes changes, which is already clear.

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 it provides detailed change history (status, stage, loss reason) and distinguishes itself from the sibling 'get_deal_summary' by recommending that for a full view.

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 advises when to prefer 'get_deal_summary' over this tool, but does not address other sibling tools or general usage context beyond that.

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 no annotations provided, the description carries the full burden. It discloses the comprehensive set of returned data (activities, notes, movement history, etc.), giving the agent clear expectations. It does not discuss side effects or limitations, but the read-only nature is implied by 'analisar' and the context is adequate.

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 concise, front-loading the purpose ('PREFERENCIAL para analisar deals') and then efficiently listing the returned components. Every sentence adds value 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 tool has only one parameter and no output schema, the description sufficiently explains what the tool returns (deal data, custom fields, linked person, activities, notes, movement history). It does not detail the output structure, but the listed items provide enough context for an agent to understand the tool's capability.

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 only parameter, deal_id, has 100% schema description coverage as 'ID do negócio'. The description adds no additional meaning or usage details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states it returns a complete view of a deal in a single call, listing specific data points (deal data, custom fields, linked person, activities, notes, movement history). This distinguishes it from sibling tools like get_deal or list_deal_activities, which return partial 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?

The description explicitly says 'Sempre usar este tool ao analisar um negócio' (Always use this tool when analyzing a deal), providing a strong usage directive. It implies this tool is preferred for analysis over more specific tools, though it does not explicitly mention when not to use it.

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?

No annotations are provided, so the description must carry the burden. It only states it returns details, but does not disclose behavior like error handling, authentication needs, or rate limits. For a simple read tool, minimal transparency beyond the purpose is insufficient.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded and to the point, efficiently conveying the tool's purpose.

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 simplicity (1 parameter, no output schema), the description is adequate but minimal. It does not hint at the structure of the returned 'detalhes completos' (complete details), which could be helpful for an AI agent. Sibling tools like search_organizations might require more context, but for a direct ID lookup, this is acceptable.

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%, with the parameter `org_id` described as 'ID da organização' in the schema. The description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns complete details of an organization by ID. It uses a specific verb ('Retorna') and resource ('detalhes completos de uma organização'), distinguishing it from sibling tools like create_organization (creates) and search_organizations (searches).

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 usage for retrieving org details by ID but does not explicitly state when to use this tool versus alternatives like search_organizations. No when-not or alternative names are mentioned.

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 no annotations, the description minimally indicates a read operation but does not detail behavior on missing IDs or other edge cases.

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, no extraneous text; highly concise.

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 get-by-ID tool with one parameter and no output schema, the description is adequate but could specify what 'complete details' entails.

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 description adds no additional meaning beyond the schema's 'ID do contato'.

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?

Description clearly states the tool returns complete details of a contact by ID, distinguishing it from sibling tools like create_person or search_persons.

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 guidance is provided on when to use this tool vs alternatives, nor any conditions or exclusions.

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?

No annotations provided, but the description discloses automatic pagination for date filters and an overdue indicator, which are important behavioral traits for a list 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, clear and structured, but slightly verbose with information already present in 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?

Cover filtering behavior and a special indicator, but missing description of return format (e.g., fields returned, pagination details) especially since no output schema exists.

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

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

Schema coverage is 100%, so parameters are well-documented. Description adds general context but no significant detail beyond the schema entries.

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?

Description clearly specifies the tool lists Pipedrive activities and enumerates filter options (user, type, period, deal, status). It distinguishes from sibling 'list_deal_activities' by implying a broader scope.

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

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

Description provides context on when to use date filters and automatic pagination, but does not explicitly state when not to use this tool or mention alternatives.

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?

No annotations are provided, so the description must carry the full burden. It does not disclose behavioral traits such as read-only nature, pagination behavior, rate limits, or data freshness. The schema shows defaults but the description adds no behavioral context beyond the basic filtering capability.

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 extremely concise with two short sentences. The first sentence states the purpose, and the second provides an alternative. No redundant or irrelevant words.

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 no output schema and no annotations, the description is minimal. It explains the purpose and alternative but lacks details about pagination, sorting, or result format. While the schema provides defaults, an agent might need more guidance on how results are ordered or how pagination works.

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 parameter already described. The description adds no extra meaning beyond stating 'filtro por status', which corresponds to the 'done' parameter but is already covered by the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists activities of a deal with status filtering. It uses a specific verb ('Lista') and resource ('atividades de um deal'), and distinguishes from the sibling get_deal_summary by advising to use it for a complete view.

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 an explicit alternative (get_deal_summary) for when a complete deal view is needed. However, it does not mention when to avoid this tool in favor of list_activities (which may list all activities globally) or other non-deal-specific tools.

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?

No annotations are provided, so the description must carry the full burden. It only states that it lists notes, but does not disclose whether the operation is read-only, requires authentication, or any other behavioral traits beyond what is implied by 'list'. While listing is typically non-destructive, the description adds no explicit behavioral context.

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

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

The description is two sentences long, front-loaded with the main purpose, and contains no unnecessary words. Every sentence adds value, making it highly concise and well-structured.

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 list tool with schema coverage of all parameters, the description covers the core functionality. However, there is no output schema, and the description does not explain the return format or confirm pagination behavior (though the schema parameter descriptions cover start and limit). It is nearly complete given the tool's simplicity.

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 input schema has 100% description coverage for its 3 parameters. The description does not add any additional meaning or context to the parameters beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Lista' (lists) and the resource 'notas de um deal' (notes of a deal). It distinguishes itself from the sibling tool get_deal_summary, which provides a more comprehensive view.

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 directs users to prefer get_deal_summary for a complete view with activities, fields, and history, providing clear when-to-use guidance and an alternative.

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 no annotations, the description effectively discloses key behaviors: pagination via start/limit (with max 500 per page), automatic retrieval of all records via buscar_todos (max 5000), and that buscar_todos ignores start/limit. This exceeds what the input schema conveys.

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

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

The description is concise, comprising two sentences that front-load the main action and then add filtering and pagination details. No extraneous 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?

Given 7 parameters, no output schema, and no annotations, the description covers core functionality but omits output details (e.g., fields returned) and potential side effects. It is adequate for a simple list tool but lacks completeness for complex edge cases.

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 description adds limited new meaning. It reinforces filter parameters (status, pipeline) and pagination parameters, but does not add details beyond schema descriptions. The mention of automatic retrieval is useful 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 the tool lists Pipedrive deals, with filtering by status and pipeline. It distinguishes from other list tools (e.g., list_activities) by specifying the resource (deals). However, it does not explicitly differentiate from search_deals, which could also retrieve 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?

No guidance is given on when to use this tool versus alternatives like search_deals or other list operations. The description only explains what the tool does, not when it is appropriate to use.

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?

No annotations provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or whether the list is paginated (beyond schema).

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

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

Single sentence with no fluff, efficiently conveying the core purpose. However, it could be more descriptive without losing conciseness.

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

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

No output schema exists, yet the description does not hint at the return structure or fields. Given the simplicity of the tool (2 optional parameters), more context could be 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning to the parameters beyond what 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?

Description clearly states verb 'Lista' and resource 'produtos disponíveis no Pipedrive', making the purpose evident. No sibling tool duplicates this function.

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 guidance on when to use this tool versus alternatives. Although no direct competitor exists, the description does not provide any usage context or preconditions.

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?

No annotations are provided, so the description carries the full burden. It only hints at searched fields (title, contact, company) but does not disclose other behaviors like case sensitivity, search syntax, empty results handling, or output format. The description is too minimal to inform the agent beyond basic purpose.

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

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

The description is a single concise sentence with no wasted words. It front-loads the essential information and is appropriately sized for a simple search tool. 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?

Given the low complexity (2 params, no output schema, no nested objects), the description is adequate but lacks behavioral details like pagination, sorting, or search algorithm. It does not explain the return format, which is important for an agent to interpret results. However, the tool is simple and siblings provide context.

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?

Input schema has 100% description coverage for both parameters, providing baseline of 3. The description adds value by specifying that the term searches across 'título, conato, empresa' (title, contact, company), which is not in the schema. This helps the agent understand the search scope. The limit parameter is not mentioned, but the schema already describes it.

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 'Busca' (search), the resource 'negócios' (deals), and the scope 'por termo (título, conato, empresa)' (by term: title, contact, company). This distinguishes it from sibling tools like list_deals (which lists all deals) and search_organizations/search_persons (which search other entities).

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 usage when searching deals by keyword but does not explicitly state when to use this tool vs alternatives. No guidance on when not to use it (e.g., for listing all deals) or any prerequisites. The agent must infer from the tool name and 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It only implies read-only operation (search) but does not mention any behavioral traits like pagination, performance, or side effects. Transparency is minimal.

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

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

The description is a single concise sentence, efficiently conveying the core purpose. While it could add minimal context, it avoids unnecessary verbosity.

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?

Without an output schema, the description should explain what the search returns (e.g., list of organizations, IDs, etc.). It does not, leaving the agent with incomplete information for a search 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 coverage is 100%, with both parameters described in the input schema. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action (search) and the resource (organizations/companies) in Portuguese, making the purpose unambiguous. However, it does not explicitly differentiate from sibling search tools like search_deals or search_persons, though the tool name and context may suffice.

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 no guidance on when to use this tool versus alternatives, such as search_persons or search_deals. It only states the basic function, leaving the agent without context for selection.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool is a read-only search operation but lacks details on matching behavior (partial, exact), case sensitivity, or return format. This is adequate but minimal.

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 sentence, front-loaded with verb and resource, with no wasted words. Perfectly concise for the information it conveys.

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 low complexity (2 params, no output schema), the description is nearly complete. It explains the tool's purpose and search criteria. It could mention that limit is optional and defaults to 10, but that is already in the schema. Overall 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 coverage is 100% (both parameters described), so baseline is 3. The description adds value by specifying that the 'term' can be a name, email, or phone number, which the schema does not. However, it does not mention the 'limit' parameter. No enrichment beyond baseline.

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

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

The description clearly states the verb 'busca' (search) and the resource 'contatos' (contacts/persons), specifying search criteria (name, email, phone). It effectively distinguishes from sibling tools like 'search_deals' or 'search_organizations'.

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 tells when to use this tool (search contacts by name/email/phone) but does not mention when not to use it or suggest alternatives like 'get_person' for known IDs. The context is clear though not 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?

No annotations are provided, and the description lacks details on side effects, required permissions, or whether it overwrites existing data, leaving the agent with limited behavioral insight.

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 concise sentences with the key information front-loaded; no unnecessary words.

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 has no parameters and no output schema, the description sufficiently covers purpose, usage, and outcome.

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 zero parameters, the description does not need to add parameter-level detail, and the baseline of 4 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 clearly states it synchronizes everything from Pipedrive into a config.js file, distinguishing it from sibling tools that handle individual entities.

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

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

The description explicitly states when to use this tool (after installation or configuration changes) and implies it is a one-time setup 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?

With no annotations, the description carries full burden. It mentions accepting name/ID for type and responsible and local timezone for times, but does not disclose idempotency, side effects (e.g., notifications), or whether partial updates are supported. For a tool with 10 parameters, more behavioral context is needed.

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 concise (two sentences) and front-loaded with core purpose. However, it is in Portuguese, which may reduce immediate clarity for non-Portuguese speakers, but it is still 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?

Given the complexity (10 parameters, no output schema), the description covers main capabilities and parameter flexibility but lacks info on return values, error conditions, or prerequisites. Adequate but with gaps.

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 baseline is 3. The description adds that type and user_id accept name or ID, and times are in local timezone, but these are already in the schema descriptions. No new semantic value beyond 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 clearly states the tool updates an activity and lists specific actions: mark done, reschedule, change responsible or type. It uses the verb 'Atualiza' and resource 'atividade', and distinguishes from siblings like create_activity.

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

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

The description implies use for updating existing activities, but does not explicitly state when to use vs alternatives or when not to use. No mention of prerequisites or exclusions.

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 no annotations, the description must disclose behavior fully. It mentions the ability to update fields and accept name/ID for some parameters, but lacks details on side effects, authentication requirements, rate limits, or conditional requirements like 'lost_reason' when status is 'lost'. The behavioral disclosure is minimal.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose and a key capability. It is concise without being overly terse, though it could benefit from a slightly more structured format.

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 no annotations, the description is too brief. It omits conditional requirements (e.g., lost_reason when status=lost), does not explain return values, and lacks context on side effects or constraints. The tool is complex but the description leaves many gaps.

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 that name or ID can be used for pipeline, stage, and responsible, but this is already present in the parameter descriptions. No additional semantic value 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 clearly states the tool updates a deal, listing key fields like status, stage, pipeline, value, etc. It also highlights the ability to accept name or ID for pipeline, stage, and responsible. However, it does not distinguish itself from sibling 'update_deal_fields', leaving room for ambiguity.

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 guidance is provided on when to use this tool versus alternatives like 'create_deal' or 'update_deal_fields'. There is no mention of prerequisites or when not to use it.

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 no annotations, the description fully discloses key behavioral traits: it will not overwrite existing fields without force=true, and returns conflicts for user decision. This is critical for a mutation tool. Could mention other details like error handling, but the main behavior is clear.

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

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

The description is front-loaded with the main action, then provides important usage details. Each sentence adds value. Slightly longer due to warnings, but still concise for the complexity.

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 mentions returning conflicts, but does not fully explain the return format (e.g., on success). Given no output schema, it could be more complete. However, it covers the most important behavioral aspects and parameter usage thoroughly.

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 parameters have descriptions), baseline 3. The description adds significant value beyond the schema: explains JSON format, enum exact text, set comma-separated, and the force parameter's condition. Includes an example.

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 explicitly states 'Atualiza campos personalizados de um negócio' (updates custom fields of a deal), with a specific verb and resource. It clearly differentiates from sibling tools like update_deal (standard fields) and create_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?

Provides clear instructions on when to use (for custom fields), how to format enum and set values, and crucially warns about the non-overwriting behavior and the need for user confirmation before using force=true. However, it doesn't explicitly contrast with other tools for standard updates.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions editing and pinning but omits details about permissions, side effects (e.g., notifications), or reversibility. The mutation nature is implied but not elaborated.

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

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

The description is a single concise sentence that front-loads the primary action. Every word contributes meaning, 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?

For a tool with 3 parameters and no output schema or annotations, the description adequately explains core functionality. However, it lacks details on default behavior when optional parameters are omitted, potential errors, or return values, leaving gaps for an agent.

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 parameters are already documented. The description adds minimal extra by confirming HTML support for content and clarifying that pin/unpin relates to a deal. This is consistent with the schema but does not significantly enhance understanding.

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 'Edita' (edits) and the resource 'nota' (note), with specific actions: editing content and pinning/unpinning in a deal. It distinguishes from sibling tools like create_note and list_deal_notes by focusing on modification of existing notes.

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 usage for updating existing notes but does not explicitly state when to use this tool versus alternatives such as create_note or list_deal_notes. No exclusions or prerequisites are mentioned.

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 no annotations, the description should fully disclose behavior. It mentions the pre-update check and additive behavior, but fails to disclose the destructive potential of the 'force' parameter, the prerequisite for 'custom_fields' (sync_person_fields), and the nature of updates for other fields (overwrite vs. merge).

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 concise sentences plus an important note. Every sentence adds meaningful information, with the core action upfront and critical behavioral notes following 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 7 parameters, no output schema, and no annotations, the description is incomplete. It omits the 'force' parameter's implications, the prerequisite for 'custom_fields', the return value or side effects, and does not differentiate the update behavior for organization field. Sibling tools like 'create_person' further highlight missing context.

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% (baseline 3). The description adds value by clarifying that email and phone are added, not replaced. However, it does not describe 'force' or 'custom_fields' beyond what the schema says, missing an opportunity to add further semantic 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 the tool updates a contact with specific fields (name, email, phone, organization). It distinguishes from sibling tools like 'create_person' and other update tools by specifying the resource and the additive behavior for email and phone.

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 warns about checking existing fields and overwrites, and clarifies email/phone are added. However, it omits guidance on when not to use the tool (e.g., for replacing email/phone) and doesn't mention the 'force' parameter's crucial role in bypassing warnings.

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