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

Annotations already indicate it's not read-only. The description adds no new behavioral details (e.g., idempotency, side effects, or whether it creates a new record). The openWorldHint is not explained.

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 one short sentence, concise and to the point. It is front-loaded with the key action. 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 add operation, but it does not mention that the deal ID must exist, or what the tool returns. Given no output schema, additional context could help.

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 each parameter's description already exists. The tool description doesn't add any extra meaning beyond 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 action (add) and resource (discount to a deal). It distinguishes from sibling tools like update, list, or other add tools. However, it could be more precise about what 'additional' means.

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 such as pipedrive_update_deal_discount or pipedrive_list_deal_discounts. No prerequisites or context 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?

Annotations indicate it is not read-only, not destructive, not idempotent, and open-world. The description merely states the action without additional behavioral traits like authentication needs, side effects, or error handling. It adds no value 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?

Single sentence, front-loaded with the action, no unnecessary words. Perfectly 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 tool with two required parameters and no output schema, the description is minimally adequate. However, it lacks context on error cases (e.g., duplicate followers, invalid IDs) and the exact behavior of the 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% (both parameters described). The description adds no additional meaning beyond what the schema already provides. 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 ('Add a follower') and the resource ('a deal'). Among sibling tools, there are similar add_follower tools for other resources, but the name and description together disambiguate. However, it does not explicitly differentiate from siblings.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., when to add a follower vs. remove or list followers). No prerequisites or context about 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?

Annotations already indicate write operation. Description adds that it adds an installment, but doesn't describe side effects or error behavior when prerequisites are not met. No contradiction with 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 sentences: first states action, second gives prerequisites. No extraneous words, front-loaded with key verb and resource.

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

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

Covers prerequisites well. Missing return value info (e.g., returns the created installment). Given low complexity and no output schema, this is a minor gap.

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

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

Input schema has 100% coverage with descriptions for all parameters. The description does not add further detail beyond the schema, so baseline score 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 it adds an installment (payment schedule entry) to a deal. It distinguishes from siblings like pipedrive_add_deal_discount and pipedrive_add_deal_product by specifying 'installment' and providing prerequisites.

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 prerequisites are given (Growth+ plan, deal must have one-time product and no recurring products). However, it doesn't explicitly state when not to use or name 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation that is not destructive. The description adds 'attach' but reveals no further behavioral traits, such as whether the deal total is recalculated, whether the product must exist, or what happens on failure. It does not contradict annotations, but adds minimal value beyond them.

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 with no redundant or filler content. It clearly states the action and object in minimal words, making it very concise and easy to parse.

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 14 parameters including optional billing fields and multiple sibling tools for deal products, a one-line description is insufficient. It does not explain when to use this versus bulk operations, mention prerequisites like existing deal/product IDs, or highlight notable optional behaviors (e.g., recurring billing). The agent would need to rely heavily on the schema and sibling names, risking incorrect selection.

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

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

Schema description coverage is 100%, meaning all 14 parameters already have descriptive text in the schema. The tool-level description does not add any parameter-specific context beyond what the schema provides, 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 states a specific verb ('attach'), a specific resource (a single product as a line item to a deal), and it distinguishes itself from siblings like pipedrive_bulk_add_deal_products and pipedrive_update_deal_product by emphasizing 'single' and the add semantics. An agent can immediately understand the core function and differentiate it from related tools.

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

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

No guidance is provided about when to use this tool versus alternatives like bulk_add_deal_products or update_deal_product. The description does not mention any conditions, prerequisites, or contexts, leaving the agent to infer usage solely from the operation name and schema.

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 indicate readOnlyHint=false and destructiveHint=false, so the description aligns with them. However, the description adds no extra behavioral context such as permission requirements, side effects, or rate limits, relying fully on annotations.

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

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

The description is a single sentence, which is concise but lacks any structure. It is not verbose, but could benefit from slightly more detail 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?

Given the lack of output schema and minimal annotations, the description is too sparse. It does not explain what happens after adding the follower (e.g., notifications, duplicate handling), leaving the agent with insufficient context for complete understanding.

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 'id' and 'user_id' documented. The description does not add any additional meaning beyond what the schema 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 action 'Add a follower to an organization' with a specific verb and resource. Among sibling tools like pipedrive_add_deal_follower, pipedrive_add_person_follower, etc., it is clearly distinguished by the entity type.

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, when not to, or any alternatives. No prerequisites or context are mentioned, which is a significant gap given the existence of multiple follower-related 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?

Annotations already declare readOnlyHint=false, so the agent knows this is a write operation. The description adds no further behavioral context, such as whether the operation can fail, or what happens if the follower already exists.

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

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

The description is a single sentence with 6 words, no redundancy, and directly states the 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?

Despite low complexity, the description lacks information about return values, error conditions, or outcomes. For a write tool with no output schema, this is insufficient for an agent to understand what to expect.

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 basic descriptions for both parameters. The description does not add any additional meaning or context beyond what the schema already provides.

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

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

Description clearly states the action ('Add a follower') and the resource ('to a person'). It distinguishes from sibling tools like pipedrive_add_organization_follower and pipedrive_add_deal_follower by specifying the entity type.

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. There is no mention of prerequisites, context, 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?

Annotations indicate this is a mutating operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no additional behavioral context, such as required permissions, side effects like notifications, or response format. The minimal description does not enhance transparency 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?

The description is a single concise sentence with no extraneous words. It efficiently communicates the tool's primary function.

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?

While the tool is simple, the description lacks information about success/error outcomes, return values, or any post-invocation behavior. Given there is no output schema, the agent is left without knowing what to expect after execution. The description is incomplete for practical 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?

Input schema has 100% coverage with clear descriptions for both parameters (product ID, user ID). The description does not add further meaning beyond the schema. Baseline score of 3 is appropriate as the schema already provides sufficient parameter semantics.

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 'Add a follower to a product' clearly specifies the action (Add) and resource (follower to a product). It effectively distinguishes this tool from sibling add_follower tools for other entities like deals, organizations, and persons, as implied by the tool name and description.

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 other add_follower tools for different entities. There is no mention of prerequisites, context, or conditions under which adding a follower is appropriate.

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 indicate mutation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds no further behavioral context, such as permission requirements, side effects, or error conditions.

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, clear sentence with no extraneous information. It is appropriately front-loaded and 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?

The description is adequate for a simple creation tool but lacks details on return values, error handling, or post-creation behavior. Given the lack of output schema and annotations providing some context, it is minimally complete.

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

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

Schema coverage is 100%, with all parameters described in the schema. The description adds no additional meaning beyond the schema, achieving the baseline for high 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 clearly specifies the action ('Add'), the resource type ('variation'), and the target ('product'), distinguishing it from sibling tools like pipedrive_create_product or pipedrive_add_product_follower. However, it does not elaborate on the concept of a variation (e.g., size, color) beyond the schema.

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

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

No explicit guidance on when to use this tool versus alternatives like pipedrive_create_product or pipedrive_add_product_follower. The usage context is only implied by the name and description.

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

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

The description explains the effect (setting status to archived) and adds context about the add-on requirement and beta status. Annotations indicate idempotentHint=true and no destructiveness, which are consistent with the description.

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, clear sentence plus a concise parenthetical note. No unnecessary words, perfectly 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?

Given the simplicity of the tool (one required parameter, no output schema), the description adequately covers purpose, effect, and prerequisites. It could mention the impact on listing visibility, but overall sufficient.

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

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

The only parameter 'id' is described in the schema as 'Project ID to archive'. The description does not add additional meaning beyond what the schema already provides. With 100% schema coverage, baseline is 3.

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 ('Archive a project') and the resource (project). It distinguishes from sibling tools like update_project or create_project by specifying the archiving action.

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 mentions the requirement for the Projects add-on and that the API is in public beta, providing context for usage. However, it does not explicitly state when not to use this tool or suggest 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?

Annotations already establish a write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds the batch-size ceiling ('up to 100'), which is useful. However, it does not disclose failure semantics for bulk operations (e.g., partial success, all-or-nothing validation) or whether the call appends to or replaces existing products, leaving openWorldHint=true under-explained.

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

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

A single, front-loaded sentence with zero filler. The key qualifiers 'Bulk', 'up to 100', and 'in one request' all precede the noun and convey maximum meaning in minimal 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 bulk mutation with a complex nested payload (11 properties across line items) and no output schema, the description is thin. It leaves undefined what happens on partial failure, how existing deal products are affected, and whether items validate atomically. The rich schema covers parameters, but behavioral context for a bulk write is missing.

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

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

Schema description coverage is 100% and the nested data array properties (tax, discount, billing_frequency, etc.) are fully documented in the schema. The description adds no parameter-level detail, so the dimension sits at the baseline where the schema carries the 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?

The description states a specific verb ('Bulk-add'), resource ('line-item products'), target ('a deal'), and a batch limit ('up to 100'). The 'bulk' qualifier distinguishes it from pipedrive_add_deal_product and pipedrive_update_deal_product, though it never names them explicitly.

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

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

The description implies the batch context ('up to 100 line-item products in one request') and contrasts implicitly with single-item siblings, but it does not explicitly state when to prefer this tool over pipedrive_add_deal_product or note any exclusions or prerequisites.

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

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

Annotations provide minimal behavioral info (readOnlyHint=false, destructiveHint=false). The description only states 'Create' but doesn't disclose creation behavior, side effects, success/error outcomes, or quotas. It adds little 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?

The description is extremely concise at two sentences, with the first sentence stating the purpose and the second highlighting key requirements. Every word is necessary.

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 (19 parameters, nested objects, no output schema), the description is too brief. It lacks details on return value, validation rules, or behavioral context, making it insufficient for an agent to fully understand the tool's effects.

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 100% schema description coverage, the schema already details all parameters. The description only reiterates that subject and type are required, which is already in the schema's required array. No extra semantic value is added.

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' and the resource 'activity in Pipedrive', with required fields mentioned. It distinguishes from sibling tools like pipedrive_update_activity and pipedrive_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?

Beyond stating that subject and type are required, the description gives no guidance on when to use this tool vs alternatives (e.g., using pipedrive_update_activity for updates) or any prerequisites or limitations.

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 indicate it's a write operation (readOnlyHint=false), not destructive, and not idempotent. The description adds only the note about the add-on and public beta. It does not disclose side effects, prerequisites, or behavior beyond creating a board, which is already implied. No contradictions with annotations.

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

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

The description is concise, with a single clear statement of purpose and a parenthetical note. It is front-loaded and efficient, though it could include structured bullet points for better readability.

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 creation tool, the description covers the basic purpose and required parameter. However, it lacks context about whether the board belongs to a specific project (given sibling pipedrive_create_project), and the return value is not described (no output schema). It is adequate but not fully complete.

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

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

Schema description coverage is 100%, with both parameters fully described. The description redundantly states that name is required but adds no new semantics beyond 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 'Create a new project board' with the verb 'Create' and resource 'project board'. It distinguishes itself from sibling tools like pipedrive_create_project and pipedrive_create_phase by being specific to boards. However, it does not explicitly differentiate from these alternatives, preventing a perfect score.

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 minimal guidance: it notes 'name is required' and mentions 'Projects add-on; Projects API in public beta.' There is no indication of when to use this tool versus alternatives like pipedrive_create_project or pipedrive_create_phase, nor are prerequisites or context provided.

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 provide readOnlyHint=false, destructiveHint=false, etc. Description adds that only title is required, but does not disclose side effects, permissions, or response behavior. With annotations present, minimal additional value.

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 that is front-loaded with the tool's purpose and key constraint. 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?

Tool has 14 parameters with 100% schema coverage but no output schema. The description does not mention return value, typical usage, or prerequisites. For a create tool with many optional fields, more context on behavior after creation would be helpful.

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 detailed parameter descriptions. The description only reiterates the required field, adding no new semantic info. Baseline 3 appropriate.

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

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

Description clearly states 'Create a new deal in Pipedrive' with a specific verb and resource. It also distinguishes from sibling tools like pipedrive_update_deal by focusing on creation. The requirement of only title is highlighted.

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 indicates when to use (creating a deal) and notes that only title is required, but lacks explicit when-not-to-use or alternatives. However, sibling tools imply clear distinctions.

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 declare readOnlyHint=false and openWorldHint=true, indicating an unconstrained mutation. The description adds genuinely useful behavioral context: it reveals the return payload shape (response.data.field_code) and instructs the agent to retain that 40-char hash for later updates/deletes. This anticipates a real workflow need beyond what annotations provide. No contradiction with annotations found.

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

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

Two dense sentences with zero filler. The core purpose is front-loaded, followed immediately by the most important parameter constraints. The field_code guidance gives a forward-looking note without bloat. Slightly more detail on the field_code implications could be added, but the current text is efficiently 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?

With no output schema present, the description correctly carries the return-value burden by documenting the field_code that must be preserved. It covers required parameters and the conditional options requirement. It doesn't detail auth/error handling, but for a field-creation tool where annotations signal an open-world, non-destructive operation, the essential call-time context is present.

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 of all 7 parameters, but the description adds value by surfacing the conditional dependency between options and enum/set field types, and by re-emphasizing the two required parameters. Since the schema already documents each parameter, the description's reinforcement of the options-required-for-enum/set rule is meaningful added guidance rather than repetition.

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

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

The description opens with 'Create a deal custom field' — a specific verb + resource combination that clearly states the operation. The 'deal' qualifier distinguishes it from siblings like pipedrive_create_person_field, pipedrive_create_organization_field, and pipedrive_create_product_field. An agent can immediately tell this is the right tool for creating a custom field on deal records.

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

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

The description gives parameter usage guidance — field_name and field_type are required, and options is required for enum/set types — which helps the agent assemble a valid request. However, it doesn't explicitly address when to use this tool versus its siblings (create_person_field, create_organization_field, etc.) or mention any exclusions. The differentiation relies on the name itself rather than the description.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds the linking requirement but does not disclose additional behaviors like idempotency or error handling. No contradiction with annotations.

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

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

The description is a single sentence that is front-loaded with the action and includes essential constraints with no extraneous 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?

For an 8-parameter creation tool with no output schema, the description covers the most critical business rule but lacks explanation of other important parameters like value, owner_id, or visible_to. The sibling context includes many create tools, but the description only minimally differentiates.

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 a critical business rule: 'link to at least one of person_id or organization_id', which is not enforced by the schema alone. This extra guidance justifies above 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 'Create a new lead in Pipedrive' with a specific verb and resource, and adds a key constraint about linking to person/org, which distinguishes it from sibling tools that create 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 for creating leads and notes a requirement (link to person/org), but does not explicitly differentiate when to use this tool vs alternatives like pipedrive_create_deal or pipedrive_create_person.

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 indicate non-readOnly and non-destructive. The description adds that content is required and linking is possible, but does not disclose potential side effects, permissions, or return values.

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

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

Two sentences, front-loaded with the purpose, and no wasted words. Efficient and to the point.

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

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

Covers creation and linking but omits mention of return value (e.g., note ID), pin flags, content length limits, or other constraints. Adequate but not comprehensive.

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 has 100% coverage with detailed descriptions for each parameter. The description reiterates required content and linking options but adds no 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 'Create a new note in Pipedrive', specifying the verb and resource. It distinguishes from sibling tools (e.g., create_deal, create_activity) by focusing on 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 when to use (create note) and notes required content. However, it does not explicitly state when not to use this tool (e.g., for updating notes) or compare with alternatives like pipedrive_update_note.

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 indicate readOnlyHint=false, so the mutation behavior is known. The description adds no additional behavioral context such as side effects, permissions, rate limits, or response behavior, leaving agents with minimal extra 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?

The description is a single, front-loaded sentence of seven words, conveying the essential action and the only requirement without any filler.

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

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

Given the tool has 7 parameters (including a nested address object) and no output schema, the description lacks details about return values, error handling, or integration with other Pipedrive entities, making it incomplete for full agent understanding.

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 merely reiterates the required status of name, adding no new semantics beyond what is in the schema.

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

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

The description uses the specific verb 'Create' and resource 'organization', clearly distinguishing it from sibling tools like pipedrive_create_deal or pipedrive_create_person. It also specifies the only required field (name), adding precision.

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 states 'Only name is required', which indicates a mandatory field but provides no explicit guidance on when to use this tool versus alternatives (e.g., update tools or other create tools). Usage is implied but not elaborated.

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 adds context about required parameters and the field_code in the response. Annotations already indicate non-destructive, non-readonly behavior; description does not contradict and provides moderate additional behavioral info.

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 (3 sentences) with no unnecessary information. It front-loads the main action and follows with key details. Every sentence is useful.

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?

While the description covers essential points, it lacks information about the return value structure beyond field_code. Given the complexity of the input schema (nested objects), a bit more context on the response would improve completeness.

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 description adds value beyond the schema by emphasizing required fields and the condition for options. It also notes the response includes field_code for future updates. Schema coverage is 100%, so baseline 3, but description provides extra meaningful guidance.

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's purpose: 'Create an organization custom field.' It specifies required parameters and conditions for enum/set types, distinguishing it from other field creation tools.

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

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

The description implies usage for creating organization custom fields but does not explicitly guide when to use this tool versus alternatives like create_deal_field or provide use/no-use cases.

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 indicate non-readonly, non-destructive, non-idempotent, and open world. The description adds the constraint that only name is required, which is useful but already implied by the schema. No additional behavioral details like side effects or limitations.

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?

Extremely concise with two sentences, front-loading the action. Could potentially add more detail without becoming verbose, but it's 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?

With 10 parameters, nested objects, and no output schema, the description is too brief. It does not explain return values, error handling, or what happens on success. The agent may need more context to correctly interpret 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%, so all parameters are described in the schema. The description reinforces that name is required, which matches the schema's required field. No new semantic meaning beyond what the schema provides.

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

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

Clearly states the tool creates a new person/contact in Pipedrive with a specific verb and resource. Differentiates from sibling tools like create_deal or 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?

Mentions that only name is required, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., creating an organization or lead). No when-not scenarios or competitor tools 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?

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds that the response includes a field_code for later updates. It does not elaborate on other behaviors like idempotency or limits, so it provides moderate added value.

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

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

The description is two sentences, front-loading the core purpose and then providing critical usage details. 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?

For a create tool with detailed schema and no output schema, the description covers required fields, special cases, and the response field_code. It could mention potential errors or uniqueness constraints, but it is largely complete.

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

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

With 100% schema description coverage, the baseline is 3. The description goes beyond by highlighting that options is required for enum/set types and that the response field_code is important for updates, adding value over the schema alone.

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 creates a person custom field, a specific verb-resource pair. It distinguishes from sibling tools like pipedrive_create_deal_field or pipedrive_create_organization_field by explicitly mentioning 'person custom field'.

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 indicates when to use this tool by specifying required parameters and noting that options is required for enum/set types. It does not provide explicit alternatives or when-not-to-use guidance, but the context is 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 indicate it is a write operation (readOnlyHint false) with no destructive or idempotent hints. The description only restates 'create,' adding no new behavioral context such as side effects, authorization needs, or error conditions.

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—one sentence plus a parenthetical—with no wasted words. The purpose is stated first, fulfilling the front-loading principle.

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 creates a new entity (phase) with three parameters and no output schema, the description lacks important context: what a phase is, its relationship to boards/projects, any uniqueness constraints, or expected response behavior. The openWorldHint suggests side effects, but these are not explained.

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

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

The input schema has 100% description coverage, so the schema already fully documents each parameter. The description redundantly mentions required fields but adds no additional semantic meaning beyond what the schema provides.

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

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

The description clearly states the purpose as 'Create a new project phase,' using a specific verb and resource. Among sibling tools, only this one is for creating phases, so it is well-distinguished.

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 mentions required parameters and the Projects add-on beta status, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., create_stage) or any 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?

Annotations already indicate it's not read-only, not destructive, not idempotent, and open world. The description adds that name is required and that is_deal_probability_enabled controls weighted probability. However, it does not disclose potential side effects (e.g., pipeline creation implications) or authentication requirements, but this is acceptable given annotations 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?

Two well-structured sentences with no redundancy. The first sentence states the primary action, the second adds parameter details. Efficient 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?

Given the simplicity (2 params, no nested objects) and no output schema, the description is mostly adequate. However, it lacks any information about the return value or expected response, which would help an agent understand what to do after creation. This is a minor gap given the tool's straightforward nature.

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 describes both parameters. The description adds value by clarifying that name is the only required field and explaining the purpose of is_deal_probability_enabled ('turn on weighted deal probability'), which goes beyond the schema's simple type/description.

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

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

The description clearly states the action ('Create') and resource ('new sales pipeline'), and specifies that only name is required. It distinguishes this tool from sibling tools like pipedrive_create_deal or pipedrive_create_phase by the unique resource (pipeline), but does not explicitly differentiate from similar pipeline-related tools.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context of use, or when not to use it. The only instruction is that name is required and the optional boolean, but no broader usage 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 cover the high-level characteristics (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds no further behavioral context—no mention of side effects, permission requirements, reversibility, or expected outcome. For a create operation with no additional detail, the description contributes little beyond the schema.

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

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

The entire description is a single, compact sentence that immediately conveys the action and the essential requirement. No filler, no unnecessary details—maximally 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?

Given the tool's complexity (13 parameters, nested objects), the description is thin but the schema handles parameter details. Missing is any indication of what the tool returns upon success (e.g., the created product object) or any caveats about behavior, which would help an agent set expectations. It's adequate for a straightforward create but not fully complete.

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

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

Schema description coverage is 100%, so all 13 parameters are documented in the schema with clear explanations. The description's note 'Only name is required' is redundant with the schema's required array but does reinforce the minimal input needed. This is the baseline value expected when the schema is comprehensive.

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 ('Create') and resource ('product' in Pipedrive), and adds that only the name is required. It is distinct from sibling tools like pipedrive_update_product by the verb and intent, though it does not explicitly name alternatives to disambiguate further.

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

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

The description gives no guidance on when to use this tool versus alternatives such as pipedrive_update_product, pipedrive_list_products, or pipedrive_search_products. It only states the creation action without any contextual advice or exclusion criteria, leaving the agent to infer usage.

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 adds meaningful behavioral details beyond annotations: it clarifies required fields, conditional options for enum/set types, the simpler model for product fields, and the importance of the response field_code. Annotations are consistent with the create operation.

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 short and front-loaded with the main purpose. It efficiently conveys key points without unnecessary fluff, though minor restructuring could improve readability.

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 no output schema, the description explains the response field and constraints. It covers all required aspects, but lacks information on errors or side effects.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the requirements and adds nuance about ui_visibility having a simpler model, but does not significantly enhance 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 the tool creates a product custom field and specifies required parameters. However, it does not differentiate from sibling tools like pipedrive_create_deal_field or pipedrive_create_organization_field, leaving ambiguity about when to use this specific tool.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It lacks context on prerequisites, limitations, or exclusive use cases, which is a significant gap given the number of sibling field creation 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?

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds the add-on and beta context, which is valuable behavioral information beyond annotations. No 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?

Three concise sentences with no wasted words. The most important information is front-loaded: action, resource, and required fields.

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 12 parameters and no output schema, the description covers the essential context (required fields, add-on requirement). It could mention expected return value, but the schema's parameter descriptions fill most 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 the description's mention of required parameters is not adding much beyond the schema. It does not elaborate on optional parameters, which is adequate given the schema's completeness.

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 ('Create'), the resource ('a new project'), and the required fields. It distinguishes from sibling tools like pipedrive_create_deal or pipedrive_archive_project.

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 mentions the prerequisite (Projects add-on) and beta status, which helps the agent decide when to use it. However, it does not explicitly state when not to use or provide alternative tools for creating projects.

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, so the description carries a lower burden. It adds that the tool creates a stage and points to deal rotting configuration, but it does not disclose any side effects, prerequisites, or further behavioral context. It adds minimal value beyond the annotations.

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

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

The description is two concise sentences without filler. The purpose is front-loaded with the verb and resource, and the deal rotting note is efficiently placed. 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 simple create operation with full schema coverage, the description is mostly adequate. However, it does not mention the return value (e.g., the created stage object) or any implicit prerequisites like the pipeline existing. This leaves some ambiguity for the 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 all five parameters are fully documented. The description reiterates that name and pipeline_id are required and highlights the deal rotting parameters, but this adds little beyond what the schema already states. This meets the baseline for high 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 clearly states 'Create a new stage in a pipeline' with a specific verb and resource. It also identifies required parameters. However, it does not explicitly differentiate from the sibling tool pipedrive_create_phase, though the domain difference is clear from the name.

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 mentions that name and pipeline_id are required and how to configure deal rotting, but does not provide explicit guidance on when to use this tool versus alternatives like pipedrive_update_stage. The intended usage is implied (creation), but no exclusions or alternatives are named.

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

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

The description aligns with annotations (readOnlyHint=false, destructiveHint=false) and adds behavioral context: it warns that the Projects API is in public beta, and clarifies the milestone/due_date constraint and field-name consistency with GET responses. No contradiction with 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 sentences with no filler. The first sentence states the action and required fields; the second adds precise guidance on boolean fields and the beta caveat. Every sentence earns its place, and the key information is 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?

The description covers the core action, required fields, the milestone constraint, and beta status. However, it does not specify the return value (e.g., the created task object or an ID) on success, and there is no output schema. It also omits error behavior and prerequisites beyond the Projects add-on, leaving some gaps for a complex create 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?

The schema describes all 11 parameters at 100% coverage, so the baseline is 3. The description adds a minor note about is_done/is_milestone using the same field names as the GET response, but this does not significantly expand on parameter meaning beyond what the schema already provides.

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

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

The description clearly states the verb ('Create') and the resource ('a new task in a project'). It identifies required fields and provides context about the Projects API, distinguishing it from sibling tools like pipedrive_create_project or pipedrive_update_task. The purpose is unambiguous.

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

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

The description provides some usage guidance: it notes required fields, advises on boolean field names matching GET responses, and states the milestone requires a due_date. However, it does not explicitly contrast with sibling tools like pipedrive_update_task or pipedrive_list_tasks, so when-not-to-use is left implicit.

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 adds minimal behavioral context beyond the annotations. Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description only reiterates that it 'gets' information, without addressing edge cases, error behavior, or response details.

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 unnecessary words. It is well-structured for a simple tool, though it could optionally detail the optional parameter.

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 operation, the description is partially complete. However, it omits any mention of the optional 'include_fields' parameter and does not describe the return format, which is relevant given the absence of an output schema. Some context about what 'detailed information' entails would improve completeness.

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 already provides 100% coverage for both parameters (id and include_fields) with clear descriptions. The description adds no further semantic information about the parameters, so it meets the baseline but does not 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 action (Get) and the resource (detailed information about a specific activity), with the identifier (by ID). It effectively distinguishes this tool from sibling tools like pipedrive_list_activities (list) and pipedrive_create_activity (create).

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when to use pipedrive_list_activities instead. It does not mention prerequisites or context, leaving the agent without decision support.

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 destructiveHint=false, so the agent knows it's a safe read. The description adds the beta status of the API, which is important behavioral context. However, it does not mention error handling (e.g., what if ID is invalid) or rate limits, but the annotations cover the core 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?

Two sentences with no wasted words. The first sentence is the main purpose; the second is a brief context note. It could be slightly more compact (e.g., merging the parenthetical), but it's efficient overall.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete enough for an agent to understand its use. It identifies the board ID requirement and the beta status. Missing details like expected output structure are partially mitigated by the readOnlyHint annotation.

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 covers 100% of parameters (id with description 'The board ID'). The description does not add any new information about the parameter beyond what the schema already provides. With high schema coverage, 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 verb 'Get detailed information' and the resource 'specific project board by ID'. It distinguishes from siblings like pipedrive_list_boards (which returns a list) and pipedrive_create_board (which creates). The parenthetical about the Projects add-on and beta status adds context that helps differentiate this tool from other 'get' tools (e.g., pipedrive_get_project).

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 you need detailed info on a single board by ID, but it does not explicitly compare with alternatives like pipedrive_get_project (which gets a project, not a board) or when not to use it. It lacks when-to-use/when-not advice. The sibling list is large, so more guidance would be helpful.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and side-effect profile. The description adds context about the response content (company and user details) but does not disclose additional behavioral traits such as authentication requirements or rate limits. With annotations handling most behavioral disclosure, 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?

The description is two sentences, front-loaded with the primary purpose ('Identify the Pipedrive account this server is connected to') followed by the return details and use cases. There is no wasted wording, and it is efficiently 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?

Since there is no output schema, the description should ideally specify the return structure. It mentions company name, id, domain, and user details, which gives a general idea, but does not provide exact field names or nesting. For a simple tool, this is adequate, but an agent may need to infer the location of the user ID. More specificity on field names would improve completeness.

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

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

The tool has zero parameters, and the schema coverage is 100% (trivially). The description does not need to explain parameters, and the baseline for 0 parameters is 4. No additional parameter information is required.

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 identifies the connected Pipedrive account and returns company details (name, id, domain) and the API key owner's user details. It is distinct from siblings like get_user and list_users, which target specific or all users, making the purpose unambiguous.

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

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

It explicitly provides use cases: 'confirm which company the data is coming from, or to get your user ID.' This gives clear guidance on when to use it. It does not mention alternatives or exclusions, but given the tool's uniqueness, this is sufficient.

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 destructiveHint=false, so the description's addition of 'including all standard and custom fields' provides useful context but does not disclose any additional behavioral traits beyond what is safe. No contradictions.

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 with no wasted words. It efficiently conveys the purpose and scope.

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 3 parameters fully described in schema and annotations providing safety hints, the description is mostly complete. However, since there is no output schema, mentioning that the result is a full deal object adds some context, but the description is still 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%, so the baseline is 3. The description mentions 'including all standard and custom fields' but does not add significantly to the schema descriptions of the parameters.

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

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

The description clearly states the verb 'Get detailed information' and resource 'specific deal by ID', distinguishing it from other deal-specific tools like pipedrive_get_deal_conversion_status or pipedrive_get_deal_emails. It also highlights inclusion of custom fields.

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 explicit guidance on when to use this tool versus alternatives such as pipedrive_list_deals or pipedrive_search_deals. It implicitly suggests use for detailed info, but lacks when-not or alternative references.

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

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

Goes well beyond annotations by detailing the status contract (completed/failed/rejected/not_started/running), purging behavior (404 signals terminal), and that only 'completed' carries lead_id. Also warns against unbounded loops. Annotations already indicate readOnly and idempotent, but description adds critical polling logic.

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?

Description is comprehensive yet concise, with each sentence serving a distinct purpose: purpose, status contract, purge behavior, polling advice. No redundant 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 the complexity of an async polling tool, the description covers all critical aspects: status meanings, terminal states, edge case of purge, and polling strategy. No output schema, but description clarifies output expectations (lead_id only on 'completed'). Exceptionally complete.

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

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

Schema coverage is 100% and description adds context: 'id' is the deal that was converted, 'conversion_id' is the job UUID from the convert call. This helps the agent understand the origin of parameters beyond type definitions.

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?

Clearly states it gets the status of a deal-to-lead conversion job, specifying the resource (conversion job) and action (get status). However, it does not explicitly distinguish from the sibling tool pipedrive_get_lead_conversion_status, which likely covers the reverse direction.

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 guidance on when to poll (after conversion call) and when to stop (terminal statuses or 404 after prior valid status). Advises bounded poll budget. Lacks explicit comparison to alternatives but effectively tells when to use and when not to poll indefinitely.

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 adds value beyond annotations by specifying that it returns metadata only (not full body), and that the full body is only accessible for the user's own mailbox. The annotations already indicate read-only and idempotent, but the description clarifies the scope and limitation.

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 only two sentences, but it effectively communicates the core purpose, scope, and a key limitation. Every sentence serves a purpose with 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 that the tool has no output schema, the description states it returns 'metadata', which is adequate for an agent to understand what to expect. It also references the sibling tool for full body. However, the specific fields in the metadata are not described, but this is acceptable for a read-only metadata retrieval 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?

All three parameters are described in the input schema with 100% coverage. The description does not add any additional semantic meaning beyond what the schema already provides, so it meets the baseline but does not exceed 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 tool retrieves email messages linked to a deal, with company-wide scope (all users' emails). It distinguishes itself from siblings like pipedrive_get_mail_message by noting that this tool returns only metadata.

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 context for when to use this tool (to get metadata of emails linked to a deal) and points to an alternative (pipedrive_get_mail_message) for full body, but only for the user's own mailbox. No explicit when-not-to-use, but the alternative is well-motivated.

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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and behavior. The description adds no further behavioral details (e.g., pagination, changelog contents, rate limits). With annotations, a score of 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?

The description is a single sentence with 6 words, no fluff, and the key information is front-loaded. Every word is necessary and 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?

The tool is simple, but without an output schema, the description does not explain what the changelog contains (e.g., fields, actions). While annotations cover safety and the tool is low complexity, a bit more detail would improve completeness for an agent unfamiliar with the concept.

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 (id, cursor, limit) have descriptions. The description adds no additional semantics beyond what the schema provides, so baseline score of 3 is correct.

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 'Get', the resource 'followers changelog', and the scope 'for a deal'. It distinguishes from sibling changelog tools for other entities (e.g., organization, person) through the deal-specific naming.

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 when to use: to retrieve historical follower changes for a deal. It implicitly distinguishes from pipedrive_list_deal_followers (current followers) and other entity changelogs. No explicit when-not or alternatives, but the purpose is clear enough for agent 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, which establish safety and idempotency. The description adds context that the tool helps decode 40-character hash keys, going beyond structured data. It does not contradict 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 sentences: first states the core functionality, second adds a specific use case. No fluff, every sentence adds value. 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 get operation with no output schema, the description adequately explains the tool's purpose and when to use it. It could mention what 'details' includes (e.g., field name, type), but given the openWorldHint, it's acceptable. The tool is straightforward, so completeness is good.

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 the context that the key is a 40-character hash for custom fields, which reinforces the schema description. No additional parameter details beyond that, so it meets but does not exceed expectations.

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 gets details of a specific field by its key, using a specific verb ('Get') and resource ('details of a specific field'). It also mentions the use case of looking up what a 40-character hash field key means, distinguishing it from list tools like pipedrive_list_deal_fields.

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 use case: 'Useful for looking up what a 40-character hash field key means.' It implies when to use the tool (when you have a key and need field details), but does not explicitly state when not to use it or mention alternatives like list_fields. However, the guidance is adequate for an agent to understand its primary purpose.

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 adds no behavioral context beyond the annotations, which already declare the tool safe (readOnlyHint, destructiveHint false, idempotentHint). It does not disclose any additional traits like rate limits, authentication needs, or what 'detailed information' encompasses. With annotations carrying the burden, the description is adequate but not enriching.

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, clear sentence with no unnecessary words. It conveys the purpose efficiently and is 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?

The tool has a single parameter, annotations provide safety guarantees, but there is no output schema. The description says 'detailed information' without specifying return fields, which is vague. For a retrieval tool, more detail on what exactly is returned would improve completeness, but the current description is minimally 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 description coverage is 100% for the single parameter `id` (described as 'Lead UUID'). The description adds no new meaning beyond confirming the schema, so it meets the baseline of 3.

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's action ('Get detailed information'), the resource ('a specific lead'), and the identifier method ('by UUID'). It distinguishes itself from sibling tools like `pipedrive_list_leads` and `pipedrive_search_leads` which operate on collections or 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: when you have a specific lead UUID and need details. However, it does not explicitly state when to use this tool versus alternatives like `pipedrive_list_leads` or `pipedrive_search_leads`, or mention any prerequisites or context. The guidance is minimal.

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, destructiveHint=false, idempotentHint=true, covering safety. The description adds the endpoint but no additional behavioral traits like possible status values or pagination details.

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 includes the endpoint. It is concise with no unnecessary words, though it could be slightly more 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?

No output schema exists, and the description does not explain what the status response looks like (e.g., possible values). Annotations are rich but the description lacks completeness for a status-checking 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 the schema already documents both parameters. The description does not add meaningful semantics beyond what the schema provides.

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

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

The description clearly states the tool gets the status of an async lead-to-deal conversion using a conversion ID, with the API endpoint. It is specific but does not explicitly distinguish from the similar sibling pipedrive_get_deal_conversion_status.

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 vs. alternatives. It does not mention that it should be used after calling pipedrive_convert_lead_to_deal, nor does it explain 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?

Annotations already indicate readOnlyHint and idempotentHint. The description adds context about access permissions, but does not elaborate on error scenarios or behavior when body is excluded. No contradiction with 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?

Single sentence conveying the primary action, but the access caveat could be integrated more seamlessly.

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

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

Covers the core purpose and access conditions. However, does not address the output format or the openWorldHint annotation, leaving some 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 the description adds minimal value. The phrase 'with body' hints at include_body but does not clarify the default false, causing slight ambiguity.

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 email message with body', specifying the verb and resource. However, it does not explicitly differentiate from sibling tools like get_mail_thread or list_mail_threads, and the mention of 'with body' somewhat contradicts the default behavior of include_body being false.

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 access guidance regarding visibility settings and linked objects, but does not discuss when to use this tool versus alternatives 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?

Annotations already mark it as read-only and idempotent. Description adds context about visibility settings and 404 response, which is valuable 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 sentences, front-loaded with primary purpose, 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?

Complete for a simple read tool: covers purpose, access behavior, error case, no output schema needed.

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

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

Schema coverage is 100% and the single parameter 'id' is described as 'Mail thread ID'. The description adds no additional 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?

Clearly states 'Get a mail thread with messages' - specific verb and resource. Distinguishes from sibling tools like pipedrive_get_mail_message and pipedrive_list_mail_threads by focusing on a full thread.

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?

Explains access visibility and 404 error but does not explicitly guide when to use this tool vs alternatives like pipedrive_list_mail_threads to first get thread IDs.

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, destructiveHint=false, and idempotentHint=true. The description ('Get') aligns but adds no new behavioral context. With annotations present, additional 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 sentence that directly conveys the purpose. It is concise, front-loaded, and contains 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?

For a simple get-by-ID tool with one parameter, the description is mostly complete. However, it lacks details about the return value structure (no output schema), and 'detailed information' is somewhat vague. Still, it serves the basic purpose 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?

The schema already describes the parameter 'id' as 'The note ID' with 100% coverage. The description does not add any further information about the parameter's format, constraints, or role beyond what is in the schema.

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

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

The description clearly states the action ('Get'), the resource ('note'), and the method ('by ID'). It distinguishes from sibling tools like pipedrive_list_notes (listing) and pipedrive_update_note (mutation).

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 when-to-use or when-not-to-use guidance is provided. The description implicitly suggests use for retrieving a single note, but does not compare with alternatives or provide 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description 'Get detailed information' is consistent but adds no additional behavioral context beyond what annotations provide.

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 that is efficient and front-loaded. No unnecessary words or redundant details.

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?

While the description is minimal, it covers the core purpose. However, for a 'get by ID' tool with no output schema, it could clarify what 'detailed information' includes (e.g., full organization object with all fields).

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 does not add new meaning beyond the schema; it only reiterates the resource type.

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 specifies the action ('Get detailed information') and the resource ('specific organization by ID'). It distinguishes from sibling list/search tools that return multiple records.

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 you have a specific organization ID, but does not explicitly state when to use this tool vs alternatives like list or search tools. No when-not-to-use guidance is provided.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true, covering safety and idempotency. Description adds no further behavioral context (e.g., what a changelog entry contains or pagination behavior). With rich annotations, a score of 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 with no waste. Every word earns its place. Front-loaded with verb and resource.

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

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

No output schema exists, so description should explain what the changelog contains or the output format. It fails to do so. Also, pagination via cursor and limit is not mentioned. Minimal context for an agent to understand what the tool returns.

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% coverage for parameters (id, cursor, limit) with descriptions. Description does not add any additional parameter semantics beyond the schema, so baseline score of 3.

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 'Get' and resource 'followers changelog for an organization'. It distinguishes from sibling changelog tools (deal, person, product) but does not differentiate from the similar list tool (pipedrive_list_organization_followers) which returns current followers rather than changelog.

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 vs alternatives like pipedrive_list_organization_followers or other changelogs. No when-not-to-use or prerequisites 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds no behavioral context beyond what annotations provide. No contradiction, but no extra value. For a read-only get, this 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?

Single sentence, no verbose phrasing, front-loaded with key action. Every word contributes to 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?

No output schema, but the description says 'detailed information', which is vague. Given the tool is a simple get with strong annotations, the description is minimally acceptable. Could be improved by indicating what kind of details are returned.

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 clear descriptions for all three parameters (id, include_fields, custom_fields). The description does not add any additional meaning beyond the schema. Baseline 3 applies since schema does the heavy lifting.

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

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

Clearly states 'get detailed information about a specific person by ID.' The verb and resource are unambiguous. Among siblings, many get tools exist, but the resource is specific to 'person', so differentiation is natural. Lacks an explicit distinguishing feature beyond the resource name.

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 like pipedrive_get_person_emails or pipedrive_list_persons. Usage is implied: use when you need details of a single person by ID. No exclusions or alternative recommendations are provided.

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, destructiveHint=false, idempotentHint=true. The description adds value by specifying that the tool returns only metadata, is company-wide, and requires the person ID. It does not contradict annotations and provides additional 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 plus a short note, about 40 words. It is front-loaded with the main purpose and provides essential clarification about metadata versus full body. Every sentence earns its place 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?

The tool has no output schema, so the description should explain what is returned. It states 'metadata' but does not specify fields or structure. Pagination behavior (start, limit) is not described. For a simple retrieval tool, this is minimally adequate but leaves gaps for an AI 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?

All three parameters (id, start, limit) have descriptions in the schema, achieving 100% coverage. The description does not add further meaning beyond implying that id is the person identifier. The start and limit parameters are not elaborated in the description, so the schema carries the full burden.

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 retrieves email messages linked to a person, specifies it is company-wide (all users' emails), and differentiates from pipedrive_get_mail_message by noting it returns metadata only. This contrasts with sibling tools like pipedrive_get_deal_emails, though not explicitly.

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

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

The description gives context on when to use this tool (to get all linked emails across users) and provides a note about using pipedrive_get_mail_message for full body, but only for own mailbox. It does not explicitly list exclusions or alternatives for other scenarios, but the guidance is helpful.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no extra behavioral context beyond stating the resource, so it does not improve transparency 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?

The description is a single, concise sentence that is front-loaded with the core action. No unnecessary words or details.

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?

Although the tool is simple, the description does not explain what the changelog contains (e.g., timestamps, actions) or mention pagination behavior. This limits completeness for an agent generating requests without an 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% and parameters are well-described in the schema. The description adds no additional meaning or clarification beyond what the schema already provides.

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

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

The description clearly states 'Get the followers changelog for a person,' which uses a specific verb and resource, and distinguishes this tool from related siblings like pipedrive_get_person and pipedrive_list_person_followers.

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 lacks explicit guidance on when to use this tool versus alternatives like pipedrive_list_person_followers or other changelog tools. No when-not-to-use or context is provided.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by specifying that an error is returned if the person has no picture and that the output includes metadata and sized image URLs. No contradictions with annotations.

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

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

The description is concise with two sentences. The first sentence immediately conveys the core purpose and read-only nature, and the second adds an important error condition. 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's simplicity (1 parameter, no output schema), the description covers the return type and error condition adequately. It could mention that the id must refer to an existing person, but this is implied. Overall sufficient.

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

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

Schema coverage is 100% and the single parameter 'id' is already described in the schema as 'The person ID'. The description does not add any additional meaning or context to the parameter 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 'Get the picture for a person' with specific verb and resource, and distinguishes it from similar tools like pipedrive_get_product_image by specifying the resource (person picture). It also notes it is read-only.

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