Pipedrive MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.3.1
Disambiguation4/5
Tools are well-described and mostly target distinct entity-action pairs. However, some redundancy exists (e.g., deals_list_activities vs activities_list_by_deal) and the extreme number of tools may cause selection confusion.
Naming Consistency4/5
Names follow a consistent snake_case entity_action pattern, with a few exceptions like 'get_collection' instead of 'list' and longer names for bulk operations. Overall, the pattern is predictable.
Tool Count1/5
267 tools is far beyond typical MCP server scoping (3-15). While Pipedrive is complex, this volume becomes overwhelming for an agent, undermining usability and coherence.
Completeness5/5
The tool surface covers CRUD and auxiliary operations for all major Pipedrive entities (deals, persons, organizations, products, activities, leads, projects, etc.) plus system management (webhooks, roles, users). No obvious gaps in functionality.
Average 4.1/5 across 227 of 267 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 3 community issues answered or closed in the last 6 months
- 13 commits in the last 12 weeks
- Last stable release on June 28, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It only mentions search and returns, omitting pagination behavior, search algorithm (fuzzy vs exact), authentication needs, or side effects. The tool's behavior is minimally described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but at the cost of completeness. It is front-loaded but lacks sufficient detail, so it is not optimally informative for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is insufficient. It fails to clarify search semantics, pagination, or return format, and does not address the presence of a near-identical sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter, but the description adds no enrichment beyond 'name or other fields', which maps to the 'fields' parameter. It does not explain the 'term' parameter, 'exact_match' behavior, or pagination parameters, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it searches organizations by name or other fields, which is clear but does not differentiate from the sibling tool 'search_organizations' that likely performs a similar function. The verb 'search' is used but the tool's unique role among siblings is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'organizations_list', 'search_organizations', or 'search_universal'. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral details. It does not disclose side effects (e.g., whether messages are also deleted, if the action is reversible, or if it triggers any cascading operations). For a mutation tool, this is a critical gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, with no redundancy. However, the brevity omits important behavioral and usage details, which slightly reduces its effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 annotations, the description is insufficient. It fails to explain return values, error handling, or the nature of the deletion (e.g., soft vs hard). A single-line description is inadequate for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter ('id') with a schema description 'ID of the mail thread to delete'. The tool description adds no additional meaning beyond this, but since schema coverage is 100%, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark') and resource ('a mail thread as deleted'), making it distinct from sibling tools like 'mailbox_get_thread' or 'mailbox_update_thread'. However, it omits whether this is a soft or hard delete, which would enhance clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as 'mailbox_update_thread' or 'mailbox_get_thread'. No context is provided about prerequisites, typical use cases, or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks disclosure of behavior such as pagination limits, default ordering, or that 'all' may be constrained by limit parameter. Only implies a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 8 words – highly concise and front-loaded. However, it sacrifices detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, pagination, no output schema, and no annotations, the description omits crucial context about pagination usage, filter interaction, and response format. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents all parameters. Description adds no further meaning beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists activities filtered by deal. It distinguishes from 'activities_list' (general list) and 'activities_list_all_auto' (likely auto-paginated), but does not explicitly differentiate from other list variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'activities_list' or 'deals_list_activities'. Missing when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavioral traits. It only states the action, omitting details about failure modes, idempotency, side effects (e.g., notifications), or whether the operation is destructive. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately front-loaded for a simple tool, though it could include slight more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not cover behavioral expectations, error conditions, or return value information. For a mutation tool, this gap is significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters (id and user_id). The tool description adds no additional meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('follower to an organization'). It effectively distinguishes from sibling tools like organizations_delete_follower and organizations_list_followers. However, it could be more specific about the type of follower (e.g., user), but the input schema clarifies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention prerequisites such as the existence of the organization or user, or required permissions. Since annotations are absent, the description should have included contextual cues for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only says 'create', implying mutation, but no info on idempotency, duplicate handling, required permissions, or side effects. Inadequate for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with one sentence then bullet-like example for custom fields. Front-loaded with purpose, no redundancy. Could be more structured but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and 17 parameters (many address fields). Description doesn't explain return value, error handling, or address field usage details. Incomplete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds value for custom_fields with examples of formatting, but doesn't elaborate on address fields or other parameters beyond what schema says. Adequate but not enhanced significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new organization' with verb and resource. It mentions required name and support for address/custom fields. However, it doesn't explicitly differentiate from other organization tools like organizations_update or organizations_merge, but 'create' is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as organizations_merge or organizations_update. Lacks any 'when to use' or 'when not to use' instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only states 'delete', implying a destructive action, but does not disclose whether it is irreversible, what happens to related data, or any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and free of unnecessary words. It efficiently conveys the core action, though it could be slightly more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool, the description provides the essential information. However, it lacks details on reversibility, error behavior, and differentiation from bulk delete, making it somewhat incomplete for an agent's decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'id'. The description adds no meaning beyond the schema, just restating 'by ID'. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (organization) with the identifier method (by ID). However, it does not differentiate from siblings like organizations_bulk_delete, which is a similar action but for multiple organizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not specify when to use this tool versus other deletion tools (e.g., bulk delete) or mention any prerequisites or side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks any behavioral traits (e.g., read-only, side effects, rate limits). Merely states it returns a list, not enough for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loads purpose, no wasted words. However, it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 optional parameters and no output schema, the description is too brief. It does not describe return format, pagination mechanics, or filtering behavior, leaving gaps for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. Description adds no new meaning beyond 'filtering options', which is generic. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List organizations' and mentions pagination and filtering. It distinguishes from sibling tools like organizations_list_activities which list specific sub-resources, but does not explicitly differentiate from organizations_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like organizations_search. Missing context on use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states it updates. It fails to disclose side effects, required permissions, or whether changes are partial or complete overwrites. For a mutating tool, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the purpose. However, it could benefit from slightly more structure (e.g., brief notes on optional vs required).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters, no output schema, and no annotations, the description is too brief. It does not explain what the tool returns, prerequisites, or behavior with partial updates. The agent lacks sufficient context beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 13 parameters with 100% coverage. The description adds no extra meaning beyond stating 'fields to update,' which is trivially inferred. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing project,' specifying a verb and resource. It distinguishes from other project tools (e.g., create, delete) by its action, though it does not mention scope or uniqueness compared to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Provide the project ID and fields to update,' but offers no explicit guidance on when to use this tool over alternatives like projects_create or projects_delete. The context of use is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the action but does not mention side effects, permission requirements, or what happens on failure. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence and no fluff. It is appropriately sized for a simple tool, though it could be slightly expanded for clarity without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no annotations, no output schema, and sibling tools exist, the description is minimal. It explains the core action but lacks details on prerequisites, error scenarios, or duplicate handling, making it just adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds no extra meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('a user to a team'), distinguishing it from the sibling tool 'teams_delete_user'. However, it lacks nuance like specifying that both user and team must exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, such as prerequisites (user must exist, team must exist) or what happens if the user is already a member. No explicit exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states 'Get all users' implying a read operation, but does not disclose any behavioral traits such as read-only nature, pagination, sorting, or potential performance implications. This is insufficient for a safe agent decision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and directly conveys the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity (1 param, no output schema), the description lacks information about the return value. Without specifying what 'users' means (e.g., list of user objects, IDs, etc.), the agent is left guessing. The context signals indicate no output schema, so the description should compensate, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter 'id' with description 'ID of the team', achieving 100% schema description coverage. The tool description adds no additional meaning beyond the schema, such as clarifying what 'a team' refers to or any format requirements. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all users in a team' clearly states the action (get users) and the resource scope (in a team). It effectively distinguishes from sibling tools like 'teams_get_all' (all teams) and 'teams_get' (team details). However, it omits the required team ID parameter from the narrative, which is a minor clarity gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool versus alternatives like 'users_list' or 'teams_get_user_teams', nor does it mention prerequisites (e.g., the team must exist) or contextual scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Create', omitting side effects, authentication needs, or what happens on duplicate relationships. The simple verb is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks detail. It does not waste words, but also does not enrich understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 required parameters, the description is incomplete. It does not mention return values, error conditions, or how this fits with other organization tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all parameters described in schema). The tool description adds no extra parameter information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'organization relationship', distinguishing it from sibling tools like org_relationships_delete, org_relationships_get, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention prerequisites or expected context. It fails to help the agent decide among the org_relationships_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It lacks details on pagination, response format, authorization requirements, or what 'all relationships' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but under-specifies important context. It is not front-loaded with critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one required parameter, no output schema), the description is incomplete. It does not explain the response shape, limits, or any constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter org_id is fully described in the input schema (100% coverage), so the description adds no additional meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'all relationships for a specific organization', distinguishing it from sibling tools like org_relationships_get and org_relationships_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as org_relationships_get for a single relationship or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits (e.g., permissions, side effects, whether users are automatically added when specified in the array). Only states the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, which is concise but lacks important details. It is front-loaded but could be more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations exist. The description does not explain return values, error cases, or constraints. For a creation tool, more context about expected outcome is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline. The description adds no extra meaning beyond the schema; it does not clarify parameter relationships (e.g., manager_id role, effect of users array).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a new team to the company,' specifying the action (add) and resource (team). It distinguishes from sibling tools like teams_update (update) and teams_add_user (add user to existing team).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., manager_id must exist) or that users can be added via the users array or separately via teams_add_user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action (delete) without mentioning side effects, permissions, error handling, or whether deletion is soft or hard.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at six words, front-loading the purpose. However, it might be too brief, missing opportunities to add value without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description fails to provide complete context. It does not explain the return value, success criteria, or any dependencies, leaving the agent with insufficient information for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' parameter described as 'Activity ID.' The description does not add any additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an activity by ID,' specifying the verb (delete) and resource (activity). It distinguishes from the sibling 'activities_bulk_delete' by implying single-item deletion via ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'activities_bulk_delete' or contextual prerequisites. The description implies usage for deleting a single activity but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose any behavioral traits such as required permissions, rate limits, or return format, leaving the agent with minimal understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and to the point, using a single sentence to convey the core purpose without unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of retrieving thread messages, the description lacks details on return structure, pagination, or error handling, and no output schema is provided to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% description coverage for the single parameter 'id', and the description adds no additional meaning beyond what the schema already states. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'all mail messages inside a specific mail thread', distinguishing it from siblings like 'mailbox_get_thread' (gets thread itself) and 'mailbox_get_message' (gets single message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided; there is no information on when to use this tool vs. alternatives, nor 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions pagination support and the types of messages returned but omits details like sorting order, permission requirements, rate limits, or default behavior. This leaves significant gaps for an agent to safely invoke the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a summary sentence followed by bullet points, which aids readability. However, it is somewhat verbose with multiple use-case bullets that add limited value relative to length. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description provides a reasonable overview of what the tool returns and its use cases. However, it lacks details on prerequisites, error handling, and specific behavioral expectations, leaving the agent with incomplete context for robust invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are described in the input schema (100% coverage). The description adds no additional meaning beyond the schema, such as format constraints or interaction effects. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists mail messages associated with an organization and enumerates the types of data returned. However, it does not distinguish this tool from similar siblings like 'persons_list_mail_messages' or 'deals_list_mail_messages', which are likely analogous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists several use cases (e.g., reviewing communication history, understanding customer interactions) but does not explicitly state when to use this tool versus alternatives. It implies usage for organization-level email history but lacks when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It implies the project is still retrievable (non-destructive), but doesn't specify if the operation is reversible, required permissions, or side effects. This leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It is front-loaded with the main action and immediately provides additional context, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description minimally covers the operation but lacks important context like reversibility, permissions, and side effects. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description. The description adds no additional meaning about the parameter, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Archive a project' providing a specific verb and resource. It also explains that archived projects can be retrieved with a filter, adding context. However, it does not differentiate from siblings like delete or update, preventing a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a retrieval tip but fails to provide when-to-use guidance versus alternatives like delete or update. No prerequisites or exclusions are mentioned, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry full transparency. It only states a read operation but does not disclose permissions, error behavior, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no filler. However, it might be too minimal; slightly more detail could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain what 'details' entails (e.g., fields returned). Incomplete for agent to understand the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id' (type number, description 'Board ID'). The description adds no extra semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), resource ('details of a specific project board'), and method ('by ID'). It effectively distinguishes from sibling tools like projects_boards_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., projects_boards_list for listing boards). No context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It mentions required and optional parameters but omits important details such as side effects (e.g., does creating a stage affect deals or pipeline order?), authorization requirements, rate limits, or error scenarios. The range for deal_probability (0-100) is a good addition, but overall transparency is lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two main sentences followed by bullet-like examples. It front-loads the purpose and lists required fields. There is no fluff, and the structure is clean. However, it could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema), the description should probably explain the return value (e.g., the created stage object) and mention any post-creation effects (e.g., impact on deals or pipeline order). It also does not reference sibling tools for context. The examples help but are insufficient for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds practical examples and clarifies the relationship between is_deal_rot_enabled and days_to_rot, but it does not provide substantial new meaning beyond the schema. The examples are helpful but not critical.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new pipeline stage' with a specific verb and resource. It provides required and optional fields, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like stages_update or stages_delete, though the name itself implies creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists required fields and provides examples of common use cases, giving the agent a sense of when to use the tool. However, it does not specify when not to use it or explicitly contrast with alternatives (e.g., updating a stage via stages_update). The guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits, but it only states 'update properties'. It lacks details on side effects, authentication requirements, error conditions, or whether the update is partial or full.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at 7 words, with no wasted language. While short, it effectively states the purpose, though slightly more context could improve clarity without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema or annotations, the description is insufficient. It does not explain what 'update properties' entails regarding the nature of the update (e.g., partial update), return value, or additional behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 6 parameters. The description adds no additional meaning beyond what the schema already provides, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update the properties of a team' uses a specific verb and resource, clearly distinguishing it from sibling tools like teams_create and teams_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, exclusions, or context for using teams_update over other team-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full burden. It only states the action without disclosing side effects, permission requirements, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource. Very concise, though slightly more detail (e.g., on effects) would not harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is minimally adequate but lacks mention of permanence, permissions, or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds minimal value ('by its field code') 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), resource (project field), and identifier (field code), with API version. It distinguishes from sibling field deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like fields_delete_deal_field. No 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must expose behavioral traits but only states 'get details' without specifics on returned fields, auth needs, or side effects (though read-only is implied). Missing important context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, immediate clarity on purpose. Efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should compensate with return value details but doesn't. Also lacks behavioral info. Incomplete for a mailbox message retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). The tool description adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 (details of a specific mail message), and the method (by ID). It distinguishes from sibling tools like mailbox_get_thread which operates on threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like mailbox_get_thread_messages. The description does not 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose any behavioral traits such as authentication requirements, rate limits, or what 'details' entails. Fails to compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and to the point, one phrase. Not verbose, but could be improved by adding a bit more context without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple get-by-ID tool, but lacks explanation of what 'details' includes (e.g., subject, participants). No output schema to compensate. Siblings require some differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single parameter 'id'. The description adds no extra meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get', the resource 'mail thread', and the identifier 'by ID'. Distinguishes from siblings like mailbox_get_threads and mailbox_get_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like mailbox_get_thread_messages or mailbox_get_message. No when-not-to-use or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose behavioral traits such as whether the update is partial, if it requires specific permissions, or any side effects. The tool performs a mutation, but the description lacks necessary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It is concise and to the point, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and is a mutation, the description is too sparse. It does not explain the nature of the update (e.g., partial or full) or provide any operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal meaning beyond the schema, merely stating 'properties of a mail thread'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'mail thread', distinguishing it from sibling tools like mailbox_delete_thread or mailbox_get_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like mailbox_delete_thread or mailbox_get_thread_messages. The description does not provide context on appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral details such as pagination behavior, return structure, or side effects. It only states the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is too minimal. It does not explain return format, error conditions, or authentication requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; parameters are already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('List') and the resource ('files attached to a specific organization'), differentiating from sibling tools like deals_list_files or files_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., files_list for global file listing). No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'Update the properties' without disclosing effects like idempotency, error handling, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient, but could benefit from additional context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description lacks details on return values or side effects, but for a simple update tool it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with documented parameters; description adds no extra meaning beyond the schema, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Update' on resource 'organization relationship', distinguishing it from sibling tools like org_relationships_create, org_relationships_delete, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, prerequisites, or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It fails to disclose behavioral traits such as whether the operation is reversible, if it triggers side effects (e.g., notifications), or any permissions required. The description is too brief for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only two sentences with no redundant information. It front-loads the core action and follows with a specific capability (moving activities). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not mention required vs optional parameters, the behavior when only one of phase_id/group_id is specified, or what the response looks like. A mutation tool of this complexity needs more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing basic descriptions for each parameter. The description adds context that phase_id and group_id are the update fields for moving activities. However, it does not clarify that id and activity_id are required, nor does it explain default behavior when only one of phase_id or group_id is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an activity phase or group, and explicitly mentions moving activities between phases and groups. This distinguishes it from siblings like activities_update (which likely updates other activity fields) and projects_plan_tasks_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The description does not differentiate it from activities_update or other project plan tools, nor does it specify prerequisites or contexts where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavior. It only states it retrieves all teams, omitting details like authentication requirements, limits, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it could be expanded with useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool, but lacks details on return format and constraints. Could be improved with behavioral notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no extra meaning. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all teams within the company' clearly states the action (Get) and the resource (all teams), distinguishing it from sibling tools like teams_get (single team) or teams_get_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives, such as teams_get for specific teams. Lacks prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic action without disclosing whether permissions are needed, if pagination exists, or what happens if the user does not exist. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but lacks structure (e.g., bullet points). It is appropriately concise but could be slightly more informative without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not mention return format, pagination, or any constraints. Given the simple nature, it is minimal but incomplete for a comprehensive understanding. No output schema exists to supplement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all three parameters. The description adds no extra meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get all teams' and the specific scope 'that a specific user belongs to'. This distinguishes it from sibling tools like 'teams_get_all' (all teams) and 'teams_get_users' (users of a team).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a user's teams but does not explicitly state when to use this over alternatives like 'teams_get_all' or 'teams_get'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses ordering behavior but fails to mention pagination specifics, authentication requirements, rate limits, or what happens with empty folders. The behavioral disclosure is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 16-word sentence that is direct and free of redundancy. It efficiently communicates the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity, the description is acceptable but incomplete. It lacks details on return values, pagination behavior, and error handling. It provides a basic understanding but misses context needed for reliable usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description adds no extra parameter meaning beyond what the schema provides. While the schema descriptions are adequate, the description does not elaborate on how start/limit affect results or what constitutes a 'thread'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'mail threads', and specifies the folder type and ordering by most recent message. It effectively distinguishes from sibling tools like mailbox_get_thread (singular) and mailbox_get_thread_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as mailbox_get_thread for a single thread or mailbox_get_thread_messages for messages within a thread. The description does not mention any preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and does not disclose behavioral traits such as return format, error handling, authentication needs, or rate limits. Since no annotations are provided, the description carries the full burden, but it fails to add meaningful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that earns its place. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description is adequate but could be more complete by hinting at the return value or potential errors. It is minimal but not insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 'Get details... by ID.' does not add any extra meaning beyond the schema's parameter description 'Organization ID'. It provides no additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get), resource (details of a specific organization), and method (by ID). It distinguishes from sibling tools like organizations_list, organizations_search, and organizations_get_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. For example, it doesn't mention that if you need multiple organizations or don't have an ID, you should use list or search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral details. It says 'list all activities' but the schema allows filtering via the 'done' parameter, which contradicts the 'all' claim. It does not mention pagination (start, limit) or that results are scoped to the organization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core functionality without any filler words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters but no output schema. The description does not mention what the response contains (list of activity objects) or any required permissions. While adequate for a simple list, it could provide more context about the response or filtering capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description adds no additional meaning beyond the schema, making the baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('activities'), and the scope ('associated with a specific organization'). It distinguishes from sibling tools like 'activities_list' (which lists all activities globally) and 'deals_list_activities' (which lists activities for a deal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., 'activities_list' for unfiltered lists, 'activities_list_by_deal' for deal-specific activities). It does not mention filtering by done status or pagination usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It covers pagination mechanics but omits details about safety (read-only), authentication needs, or any side effects, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at around 70 words, with clear separation between purpose and features. It avoids fluff, though a bullet list could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 7 parameters and no output schema, the description explains filtering and pagination but does not mention default limits or result format. It is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the purpose of each filter (e.g., 'Filter by owner') and highlighting the get_summary parameter's role. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('products'), and mentions key features like filtering and pagination. It clearly identifies the tool's function, though it does not explicitly distinguish it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists filter parameters and pagination options, implying when to use the tool. However, it provides no comparison to alternatives like products_search or products_get, nor 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden but only states it returns type, due date, completion status; lacks details on pagination, ordering, or scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with key details, front-loaded, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal parameter and no output schema; adequate for simple list but omits potential pagination or filtering info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'id' is fully documented in schema as a number required; description adds no extra meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all activities for a specific project and lists return fields, differentiating from other activity list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives like activities_list or activities_list_by_deal; no exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It states the tool returns a 'plan structure' but does not detail what fields are included, pagination, or any side effects. Minimal behavioral information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a brief clarification. It is concise, front-loaded, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is adequate but could be more precise about the return structure. It mentions tasks, activities, phases, and groups, but does not specify the format or nesting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'id' has a basic description. The tool description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'project plan', and specifies it shows tasks, activities, phases, and groups. This distinguishes it from sibling tools like projects_plan_activities_update and projects_plan_tasks_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as projects_get, projects_phases_get, or projects_groups_list. The description lacks context for selecting the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the operation is an update, but does not disclose potential side effects, required permissions, reversibility, or any destructive behavior. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (15 words), extremely concise, and front-loads the main action. Every word is meaningful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 parameters, no output schema, no annotations), the description covers the basic function but lacks information about return values, side effects, or prerequisites. It is minimally adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with basic descriptions for each parameter. The description adds context by relating parameters to 'phase' and 'group', but does not clarify relationships (e.g., mutual exclusivity). Baseline for high coverage is 3, and the description adds only marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a task phase or group') and the resource ('in a project plan'), and distinguishes it from sibling tools like projects_update (general project update) and tasks_update (general task update) by specifying it 'Allows moving tasks between phases and groups.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 (e.g., tasks_update, projects_plan_activities_update). It implies usage for moving tasks, but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavior. It states results are ordered by relevance and implies searching across all organization fields. It lacks details on permissions, rate limits, pagination behavior (offset vs cursor), and what happens with no results. The description is moderately transparent but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Workflow tips' and 'Common use cases' sections. It front-loads the purpose. Although it is somewhat lengthy, every sentence contributes useful context. Minor redundancy with schema exists but does not detract significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters and no output schema. The description does not explain the response structure, return fields, or error handling. It mentions 'include_fields to limit response data' but does not elaborate on what the default response contains. This is a significant gap for an API tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so parameters are well-documented. The description adds value through examples (e.g., 'exact match' usage) and clarifies the 'fields' parameter with specific field names. However, the added information is not essential beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Search for organizations with advanced filtering options,' clearly indicating the verb (search) and resource (organizations). It mentions 'organization-specific search' which distinguishes it from universal search. However, it does not differentiate from the sibling tool 'organizations_search,' which appears to serve the same purpose, causing potential confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (minimum term length, fields to search, exact_match, include_fields) and common use cases with examples. However, it does not explicitly guide when to use this tool versus alternatives like 'organizations_search' or 'search_universal,' nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, default inclusion of users (implied by skip_users parameter), or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of 9 words with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools and no output schema, the description is adequate but minimal. It lacks additional context about return values or usage nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('team') and indicates retrieval by ID. It clearly distinguishes from siblings like 'teams_get_all' and 'teams_get_users'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'teams_get_all' or 'teams_get_users'. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states a read operation but does not mention permissions, error behavior (e.g., missing ID), or side effects. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, direct and front-loaded. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter retrieval tool with no output schema, the description sufficiently conveys the core function. Lacks error or return details, but acceptable given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (parameter 'id' has description 'Activity ID'). The description adds no extra meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Get' and specifies the resource 'details of a specific activity', and identifies the unique identifier 'by ID'. This distinguishes it from list tools like activities_list or activities_list_by_deal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 its siblings (e.g., activities_list, activities_get). It does not include when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions pagination and filtering but does not disclose behavioral traits such as rate limits, authentication needs, default ordering, or whether the tool lists all activities or only user-scoped ones.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main action and key features, making it concise. Minor improvement could be structured bullet points, but it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential functionality but lacks information about the return format (no output schema), pagination behavior details, and error handling. For a tool with 7 parameters and no output schema, it is moderately complete but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameter details. The description summarizes the filter types but adds no additional meaning or context beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'activities', and details pagination and filtering options, distinguishing it from creation, deletion, and other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering and pagination but does not provide explicit guidance on when to use this tool versus siblings like 'activities_list_all_auto' or 'activities_list_by_deal', nor does it include when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'Delete' but does not disclose consequences, reversibility, permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence that efficiently conveys the core purpose. Slightly higher than minimal due to no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete with two well-documented parameters and no output schema, the description provides sufficient context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds nothing beyond schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action 'Delete' and resource 'installment from a deal', distinguishes from siblings like deals_add_installment and deals_update_installment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool, prerequisites, or alternatives. Does not mention that the deal and installment must exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It notes that `field_type` cannot be changed and that options must be the full set, which adds behavioral context beyond the schema. However, it does not disclose authorization requirements, side effects, or what happens to unchanged fields. Moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear main line and a note section. Bullet points for common use cases help readability. Could be slightly more structured, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention the response format or any error conditions. For a mutation tool, it lacks information on what the API returns after update, which is needed for an agent to use it correctly. The description covers use cases but not the full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining the semantics of the `options` parameter (full set, use of `id` to preserve), which is not fully clear from the schema alone. It also ties parameters to use cases, improving meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing custom person field. The verb 'update' and resource 'person field' are specific. While the name distinguishes it from sibling field update tools, the description does not explicitly contrast them, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases (rename, add/remove options, toggle visibility) and a note on options semantics. However, it does not specify when not to use this tool or mention alternatives for updating other field types. Usage context is implied but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the tool fetches all pages automatically, but fails to mention that it is a read operation, potential performance impact, rate limits, or how the automatic pagination works. This leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding value. First sentence states core functionality; second provides usage guidance. No redundant text. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and four optional parameters, the description is too sparse. It does not explain return format, behavior when no entities match, or limitations. A more complete description would include such context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra context for parameters like 'max_items' or filters; it merely repeats the high-level purpose. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches all organizations automatically across pages, distinguishing it from likely paginated siblings like 'organizations_list'. However, it does not mention that filters can be applied via input parameters, which slightly narrows scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence 'Use this when you need complete data without manual pagination' provides explicit guidance on when to use the tool. It implicitly contrasts with alternatives that require manual pagination, such as 'organizations_list', but does not explicitly list 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only says 'list all persons', which is a read operation, but it does not disclose pagination behavior, potential performance limits, or any side effects. The schema covers parameters but the description adds no 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description is too brief. It doesn't explain what 'persons' entails, whether results are paginated (though schema has start/limit), or any important context like authentication requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with basic descriptions for each parameter (id, start, limit). The description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'persons associated with a specific organization', which is distinct from sibling tools that list other entities or list persons globally.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing persons for a given organization), but provides no explicit guidance on when to use this tool versus alternatives like persons_list or organizations_list_persons is unique, but no exclusions or scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only indicates a destructive action ('delete') but does not disclose potential cascading effects, permission requirements, irreversibility, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately concise for a simple deletion operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete tool with one parameter, the description covers the essential purpose. However, it could mention the response or error handling, but completeness is adequate given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'id'. The description adds no 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete an organization relationship', using a specific verb and resource. This clearly distinguishes it from sibling tools like create, get, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any mention of prerequisites or constraints. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching for 10 minutes, which is helpful. However, with no annotations, the description does not cover authorization needs, rate limits, or other behavioral traits. It adds some value but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with bullet-pointed tips and examples. It front-loads the main purpose. Minor redundancy in 'Common use cases' section but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 parameter, no output schema), the description provides basic purpose, caching info, and an example. However, without output schema, it does not describe the response format fully, which is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with a description for 'id'. The description includes a concrete example ({"id": 123}), which adds context. However, no further explanation of the parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List followers of a user' and explains it returns users following the specified user. However, it does not explicitly differentiate from sibling tools like deals_list_followers or persons_list_followers, though the context of 'user' is understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips like 'Shows users tracking this user's activities' and a common use case example, but does not mention when not to use this tool or suggest alternatives such as users_list for listing all users.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states input acceptance and normalization, but omits critical details like whether deletion is permanent, required permissions, error handling, or idempotency. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and a bullet-like list. It is front-loaded with the core purpose and uses no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 covers input shapes well. However, it lacks information on return format, success/error indicators, and preconditions (e.g., field existence). Some gaps remain for a fully self-contained description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the 'ids' parameter, providing baseline clarity. The description adds significant value by explaining the two accepted shapes and normalization behavior, which goes beyond the schema's technical constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete', the resource 'multiple custom person fields', and specifies it's a bulk operation. This distinguishes it from siblings like 'fields_delete_person_field' (single delete) and 'fields_bulk_delete_deal_fields' (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives (e.g., single delete). It lacks context on prerequisites, when not to use, or trade-offs. This leaves the agent uninformed about choosing the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full burden. It states the action (remove follower) and effect (stop notifications), but does not disclose side effects, auth requirements, rate limits, or response details beyond the basic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three focused sentences: purpose, effect, and a key usage note. No unnecessary words, well structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema), the description covers purpose, effect, and a parameter nuance. It doesn't explain return values or idempotency, but these are less critical for a clear delete action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial semantics by clarifying that follower_id is the relationship ID (not user_id) and directing to the list_followers endpoint, which prevents a common mistake.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a follower from a product' and explains the effect of stopping notifications. It is specific but does not explicitly differentiate from other delete_follower tools for different resources, though the tool name provides context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical note on using follower_id instead of user_id and where to get it, but does not specify when to use this tool vs. alternatives or provide any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states the action without mentioning side effects, permissions, or reversibility, leaving significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description provides the essential purpose but lacks details like confirmation of removal or potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameters (id, user_id) are self-explanatory. The description adds no additional meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove a user from a team' with a specific verb and resource, distinguishing it from sibling tools like teams_add_user or teams_get_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (removing a user from a team) but provides no explicit guidance on 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the basic behavior ('Makes one user follow another user's activities') and outcome ('Follower will see activities of followed user') but omits details on authentication, side effects, or reversibility. No annotations exist to supplement this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear sections (workflow tips, common use cases). The example JSON adds practical value. A single sentence could suffice, but structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description adequately covers purpose, usage context, and example. Slightly more detail on expected behavior would raise the score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both 'id' and 'user_id' described). The description adds an example JSON that clarifies parameter usage, but the schema already provides clear definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 a user') and the effect ('Makes one user follow another user's activities'). It distinguishes itself from sibling tools like deals_add_follower by specifying 'user' but does not explicitly compare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips ('Useful for team collaboration and visibility') and a common use case example, implying when to use the tool. However, it lacks explicit when-not-to-use guidance or comparison with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It mentions automatic pagination but fails to discuss rate limits, potential large data loads, or side effects. Insufficient for a tool that may fetch many records.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with actionable verb, no wasted words. Structured effectively for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good schema coverage, missing output schema and annotations. Description does not explain return format, pagination behavior, or max_items impact. Incomplete for a tool that could return large datasets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'fetch all activities across all pages' with a specific verb and resource. It distinguishes itself from siblings like activities_list by handling automatic pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises use when 'complete data without manual pagination' is needed, implying context. Lacks explicit when-not-to-use or alternative names, but sibling names provide differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only mentions updating and partial updates, but does not disclose behavior on failure, permissions required, side effects, or response format. This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 20 parameters, nested objects, and no output schema or annotations, the description is minimal. It does not specify return behavior, error handling, or prerequisites like activity existence. The complexity demands more information for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds value by clarifying that only provided fields are updated, which is a key behavioral semantic beyond the schema's field definitions. This helps agents understand partial update semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing activity and specifies that only provided fields will be updated. This distinguishes it from create and delete siblings, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (to update an activity) but does not mention when to avoid using it or alternatives like activities_mark_as_done for specific updates. The guidance is adequate but lacks differentiation from specialized update siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as idempotency, error states, or permission requirements. The burden falls entirely on the description, which only covers the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (description, workflow tips, common use cases). Concise without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present. The description does not explain the return value or behavior when adding a duplicate participant. However, for a simple add operation, the context is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Add a participant') and the resource ('deal'). It distinguishes participants from the primary contact and differentiates from sibling tools like 'deals_add_follower' or 'deals_add_product'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (use persons/search, person must exist) and common use cases with example objects. Lacks explicit exclusions or alternatives but gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching behavior ('Cached for 5 minutes'), which is useful. However, without annotations, the description should also indicate safety (read-only) and any side effects – these are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and well-structured with workflow tips and use cases, but slightly verbose. Could be trimmed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and the description does not detail the return format (e.g., fields in the changelog). For a list tool, more context on response structure would be helpful, though complexity is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with schema description 'ID of the deal'. The description does not add additional meaning beyond what the schema already provides. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List updates about participants of a deal' and specifies it returns a changelog. Distinguishes from sibling tools like deals_list_participants (current participants) and deals_list_updates (general updates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, but does not explicitly exclude alternative tools or provide when-not-to-use guidance. Lacks explicit differentiation from closely related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only states the operation and does not disclose behavioral traits such as read-only nature, pagination behavior, or authentication needs beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the rich schema, the description adequately conveys the purpose. However, it could mention the return format (list of deals) for completeness, but it is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema; it does not explain or contextualize parameters further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'deals', and the scope 'associated with a specific organization'. It distinguishes from sibling tools like 'deals_list' (all deals) and 'persons_list_deals'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a specific organization but does not explicitly state when to use it over alternatives like 'deals_list' or 'deals_search'. No exclusions or comparison provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the delete is not permanent, which is a key behavioral trait. However, it does not mention side effects (e.g., impact on related records), reversibility, or required permissions. Without annotations, more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no redundant words. It efficiently conveys the core action and a key behavioral trait.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is largely complete. It explains the action and the soft-delete behavior. Missing is guidance on usage context, but the simplicity of the tool makes the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'id'. The description does not add any additional meaning or context beyond the schema's 'Project ID'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'project', and adds the nuance that it marks as deleted without permanent removal, which distinguishes it from a hard delete. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like projects_archive or projects_update. The description only states what it does, not the context in which it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or what 'details' entails. A simple read operation description is minimal but sufficient for a basic understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the key action and resource. No unnecessary words. Perfect conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool without output schema, the description adequately covers the essential information. It is complete enough for its complexity, though more detail on returned fields could be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'id' described as 'Phase ID'. The description adds no additional meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details'), the resource ('project phase'), and the identifier ('by ID'). This distinguishes it from sibling tools like projects_phases_list (list all) and projects_get (get project).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance or alternatives are mentioned. The purpose implies it is for fetching a single phase by ID, but no comparison with related tools like projects_phases_list is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the need for admin permissions and that changes affect all users with the role. But it does not disclose whether the operation is idempotent, what happens on conflict, error conditions, or response format. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a brief intro, workflow tips, and common use cases. It is front-loaded with the core action. However, there is slight repetition (e.g., 'Add or update' and 'Creates or updates') that could be streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does not explain the return value or response. It covers the basic operation and permissions but lacks details on idempotency, error handling, or side effects. For a simple upsert tool, it is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes parameters with 100% coverage. The description adds value by noting that setting keys should follow Pipedrive conventions, specifying value types (string, number, boolean), and providing concrete examples. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add or update a role setting.' It specifies the action (create/update) and resource (role setting). Among siblings like roles_delete_role_setting and roles_update_role_setting, this tool is distinct as it handles both creation and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires admin permissions' and provides workflow tips and common use cases. However, it lacks explicit guidance on when to use this tool versus alternatives like roles_update_role_setting or roles_delete_role_setting. It does not specify 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions caching for 15 minutes, which is a behavioral trait. With no annotations, it misses other aspects like error handling or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections and front-loaded. It is concise but the workflow tips and use cases could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description minimally explains the return value ('settings configured'). It mentions visibility and permission settings but lacks details on return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already well-described in the schema. The description provides an example use case but does not add significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get role settings' and explains it returns all settings for a specific role. It distinguishes from siblings like roles_get_role_assignments, as it focuses specifically on settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips and common use cases, providing context for when to use. However, it does not explicitly differentiate from sibling tools or mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states the creation action and linking capability but omits information about idempotency, side effects, permission requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences covering purpose, required fields, and linking capabilities. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (19 parameters, no output schema, no annotations), the description provides essential purpose but lacks behavioral details, error scenarios, or return value hints. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by highlighting required fields and linking options. However, most parameters are self-explanatory from the schema, so the description's incremental contribution is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new activity') and identifies the resource. It distinguishes from sibling tools like activities_update or activities_list by specifying the creation action and required fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies required parameters (subject, type, due_date) and optional linking to deals, persons, etc., providing context for when to use this tool. However, it does not explicitly state when not to use it or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states 'Add an installment' implying mutation, but does not discuss idempotency, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-structured sentences: purpose and version, required fields with constraints, and a concrete JSON example. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the basics but lacks information about return values, failure modes, or prerequisites. The example helps, but completeness is average.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minor clarifications (e.g., 'name' for description, 'positive, non-zero' for amount) but largely repeats the schema's parameter descriptions, providing little extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'installment to a deal' (API v2). This distinguishes it from sibling tools like deals_update_installment or deals_add_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies required fields and their formats (e.g., amount positive non-zero, billing_date YYYY-MM-DD) and provides a JSON example. However, it does not explicitly mention when to avoid this tool or contrast it with related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'Update an existing installment' implying mutation, but does not disclose permissions, rate limits, error behavior, or side effects. Minimal transparency beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both essential. First sentence states the purpose, second provides parameter guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and parameter usage well, but lacks information about return value (no output schema) and error handling. For an update tool, typical return behavior is not mentioned, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to duplicate schema info. However, it adds value by summarizing the updatable fields ('description / amount / billing_date') and clarifying that 'id' is the deal ID, which aids interpretation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Update') and the resource ('an existing installment on a deal'). The description explicitly mentions 'API v2', distinguishing it from related tools like deals_add_installment and deals_delete_installment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on what parameters to provide ('deal id, installment_id, and any of description / amount / billing_date'). However, it does not explicitly state when to use this tool over alternatives (e.g., deals_add_installment) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral disclosure. Describes input normalization but does not mention consequences of deletion (e.g., irreversibility, cascading effects on deals), return behavior, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, directly states action and input formats. Efficient and front-loaded with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple bulk delete with one parameter and no output schema, the description covers input format and normalization but lacks details on operation outcome (e.g., whether it succeeds/fails per field, return value). Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with description. The description adds normalization behavior ('Both shapes are normalized to Pipedrive's expected ?ids= query parameter'), providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'delete' and resource 'multiple custom deal fields' with 'in a single request' distinguishing from individual deletions. Sibling tools with similar bulk delete for other entities are differentiated by the resource name in the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the operation and input formats but does not provide when to use vs alternatives (e.g., individual field deletion) or prerequisites for deletion. Implicit usage context only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'update' which implies a write operation, but does not disclose potential side effects, required permissions, or whether changes are reversible. For a mutation tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous words. It is front-loaded with the action and resource, then provides parameter guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no nested objects, no output schema), the description provides the minimal necessary information to invoke it. However, it does not explain what the tool returns or any post-update behavior, which could be important for an agent without annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds value by reiterating 'label UUID' and 'any combination of name/color', but this largely repeats what the schema already provides. No extra clarification on parameter formats or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update') and the resource ('lead label'), using a specific verb and noun. It is distinct from sibling tools like 'lead_labels_create' and 'lead_labels_delete'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to provide the label's UUID and any combination of name/color to change. This implies the correct usage scenario but does not explicitly mention when to use this tool versus alternatives (e.g., using create for new labels).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries burden. It discloses that this creates a person but lacks info on idempotency, validation, or side effects. Examples for complex fields help.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, though somewhat lengthy. Includes examples and details but remains clear. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers all parameters with examples and custom field handling. Lacks response details but is adequate for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions. Description adds value by providing detailed examples for email/phone arrays, custom_fields, and explanations for enums like visible_to and marketing_status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new person in Pipedrive.' and lists required and optional fields. It is distinct from sibling tools like persons_update or persons_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as checking for duplicates with persons_search before creation. Only field details are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It explains pagination (start/limit) and filtering options, but omits details like default sort order, behavior of combined filters, rate limits, or authentication requirements. This is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, front-loading the main action in the first sentence, followed by a bulleted list of filters and a short pagination note. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and zero annotations, the description covers basics but lacks guidance on when to prefer this over search tools or other list variants. Edge cases (e.g., multiple filters) are not addressed, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by grouping filters and explicitly mentioning manual pagination with start/limit, which is not obvious from schema descriptions alone. This improves understanding of parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all persons with optional filtering and pagination,' specifying the verb 'list' and resource 'persons.' The listed filters (user_id, org_id, first_char, filter_id) distinguish it from sibling tools like persons_list_activities or persons_list_deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 mentions optional filtering but does not direct the agent to more specific sibling tools (e.g., deals_list_persons for persons associated with a deal). No alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses pagination, sorting, and return fields but lacks details on error handling, authentication requirements, or behavior when person does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise but includes a bullet list and extra details. It could be slightly shorter without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return fields well (metadata, upload info, URL, associations). It supports pagination and sorting. Missing error handling info, but complete enough for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no significant meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all files attached to a specific person, with a detailed list of returned information. It distinguishes from sibling tools like deals_list_files by specifying 'person'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for person-specific files and mentions inclusion of related files, but does not explicitly state when to use this tool over alternatives like deals_list_files or organizations_list_files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It mentions cursor-based pagination and filtering options but lacks details on default behavior (e.g., sort order, archived inclusion default), rate limits, authentication requirements, or response structure (e.g., total count, cursor format). This is insufficient for a tool with 6 optional parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and pagination, followed by filter options. No redundant or vague language. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers main functionality but omits details about default archive state inclusion, cursor format, sorting behavior, and response structure. Given no output schema and no annotations, the description should provide more behavioral context for a list tool with 6 optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by grouping filters (status, phase, archive state) and highlighting cursor-based pagination, which summarizes the schema context. It does not repeat schema details but provides a cohesive overview.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list projects), the resource (projects), and key features (cursor-based pagination, filtering by status, phase, and archive state). It effectively distinguishes from sibling tools like projects_get or projects_activities_list by focusing on the main listing with filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing projects with filters and pagination but provides no explicit guidance on when to use this tool versus alternatives (e.g., projects_get for single project, projects_activities_list for activities within a project). Context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action (get all tasks) and output (details with assignee, status), but lacks details on pagination, authorization, or any side effects. Basic but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. The description is front-loaded with the key action and outcome.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers the basic purpose and output fields. However, it lacks details like response structure (array?), pagination, and whether it returns all tasks or only active ones, which could affect agent decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a description for 'id' as 'Project ID'. The description adds no further meaning beyond the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all tasks for a specific project, including assignee and status. This distinguishes it from the sibling tasks_list (global tasks) and other task tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when tasks are project-specific) but does not explicitly guide when not to use or compare with alternatives like tasks_list. An agent could infer, but explicit guidance would improve selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, permissions, or reversibility. It only states the update action, leaving behavioral context limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (16 words) with no redundant information, front-loading the purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is adequate. It could mention that the activity must exist, but the core functionality is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the parameter 'id' with description. The description adds no additional semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Mark an activity as done' and specifies it updates the done field to true, distinguishing it from other activity tools like activities_update or activities_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use as a convenience tool for setting done=true but does not explicitly specify when to choose this over activities_update or provide conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a write operation ('add') but does not disclose idempotency, side effects, or error handling. Prerequisites are given, but behavioral details are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, prerequisites, field lists, and an example. It is appropriately detailed without being verbose, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, yet the description does not explain the return value or response format. It covers prerequisites and fields well but lacks information on success/error responses, rate limits, or idempotency. Given the complexity (10 params, no output schema), it falls short of complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully described in the schema. The description repeats the field list and groups required/optional but adds no new semantics beyond the schema. An example is provided, which helps, but the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an incoming message to a conversation, with a specific verb ('add') and resource ('message'). This distinguishes it from sibling tools, many of which are CRUD for other entities like activities, deals, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies required OAuth scope and messaging manifest prerequisites. It does not explicitly mention when not to use or alternatives, but the context is clear for this specific action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the file is uploaded to Pipedrive and becomes part of the audit trail, but lacks details on error handling, overwrite behavior, or permissions. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (main action, workflow tips, use cases) and bullet points. Every sentence adds value, no redundancy, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description omits return value (e.g., success status, file ID). For a mutation tool, knowing the response is important for agent decision-making after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds examples and workflow tips (e.g., absolute file path), but these largely reiterate schema info without adding new semantic constraints or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach a file to a deal') and the resource, with specific use cases (contracts, proposals) and examples, making it distinct from sibling tools like deals_create or files_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with example JSON, guiding when to use the tool (e.g., attaching contracts, proposals). However, it does not explicitly differentiate from alternatives like files_upload or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses chronological ordering, included event types, and caching for 5 minutes. No annotations provided, so description carries the burden. Lacks permission or rate limit info, but adequate for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with bullet points for workflow tips and use cases. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return type (chronological list) and content types. Could be more detailed on response structure, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with a schema description. The description adds an example usage, but schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists updates about a deal, but does not explicitly distinguish from sibling tools like deals_list_activities or activities_list_by_deal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, but does not specify when not to use or contrast with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions that after creation the field's 'key' is the hash to use in person create/update payloads, and notes the 15-minute cache. However, it does not mention required permissions (e.g., admin), idempotency, or error conditions (e.g., duplicate field names). This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, using short paragraphs and bullet points. It front-loads the main action and then adds details and examples. It could be slightly trimmed (e.g., 'Common use cases' might be merged), but overall it's well-structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the result (key hash) and caching behavior. It covers the main steps for using the tool. However, it lacks information on error handling, validation, and any side effects. For a tool with 4 parameters and no annotations, it is reasonably complete but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameter purposes. The description adds value by clarifying that `options` is required for `enum` and `set` field types and by providing concrete use cases (e.g., 'Lead Source' dropdown). However, it does not explain other parameter behaviors or constraints beyond what the schema says. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a new custom field for persons.' It provides specific use cases (e.g., 'Lead Source' dropdown, LinkedIn URL, Birthday). The tool name and sibling context (e.g., fields_create_deal_field, fields_create_organization_field) further distinguish it, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: when creating custom fields for persons, and lists common use cases. It also notes that field definitions are cached for 15 minutes and suggests calling fields_list_person_fields to see the new field. However, it does not explicitly compare to other field creation tools or state when not to use this tool, which is implicit from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions that a report is automatically created to track progress. Lacks disclosure of error conditions, idempotency, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with three clear sections: intro, workflow tips, use cases. Efficiently conveys how to use the tool, though slightly repetitive in examples. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key creation aspects and provides examples, but lacks information on return values (e.g., created goal ID) and error handling. Given no output schema, description should address what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all properties. Description adds value by providing workflow tips and concrete examples (e.g., type 'deals_won' with tracking_metric 'sum'), making parameter usage clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Add a new goal to track performance metrics' and enumerates the components (type, assignee, expected outcome, duration). It distinguishes from sibling goal tools (goals_list, goals_update, goals_delete) by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with examples (e.g., track deal revenue, activities, team goals). Does not explicitly state when not to use this tool or compare with alternatives like deals_create or activities_create.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the required fields and allowed colors, but does not mention behavioral traits like idempotency, error handling, or permissions. It gives moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the primary action, lists requirements, and provides examples. Every sentence is useful, and it is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 required params, no output schema, no nesting), the description covers the essentials: purpose, required fields, allowed values, and examples. It is almost fully complete, though it could mention the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds examples and reiterates requirements, but does not add substantial new semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a new lead label.' It specifies required fields and allowed colors, and provides example use cases, making it easy for an agent to understand what the tool does and how to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives required fields and examples, but does not explicitly state when to use this tool versus alternatives (e.g., update or delete). It lacks guidance on when not to use it, such as if a label with the same name already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral consequence: 'Existing leads carrying this label will lose it after deletion.' However, it does not mention authorization requirements, error behavior (e.g., if label doesn't exist), or reversibility, which would be helpful for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first states the action, and the second explains the consequence. Every word is necessary; no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema or annotations, the description covers the main action and a critical side effect. It could be improved by mentioning possible error conditions or permission needs, but it is largely complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with the parameter 'id' described as 'Lead label UUID'. The tool description adds no additional meaning beyond the schema, just restating 'by UUID'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a lead label by UUID.' It identifies the specific resource (lead label) and the identifier (UUID). It also distinguishes from sibling tools like lead_labels_create and lead_labels_update by explicitly being the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool should be used when you want to delete a lead label, but it does not provide explicit guidance on when not to use it or prerequisites (e.g., required permissions). It mentions the side effect on leads but lacks context about alternatives or conditions for safe use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The phrase 'Get details' implies a read operation, which is appropriate. However, it does not disclose additional behavioral traits such as authentication requirements, rate limits, or whether the result includes all fields or only a subset.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no extraneous information. It is front-loaded and efficiently conveys the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema, no annotations), the description is adequately complete. It explains what the tool does without needing to detail return values (as per rules). However, it could benefit from mentioning what kind of details are returned (e.g., relationship type, dates) to be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single parameter 'id' with full coverage. The description adds no further meaning or context beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (organization relationship) with a specific qualifier (by ID). It distinguishes from sibling tools like org_relationships_get_all, org_relationships_create, etc., as it targets a single relationship by identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific ID is known, but it provides no explicit guidance on when to use this tool versus alternatives like org_relationships_get_all (for listing) or org_relationships_* mutation tools. No when-not-to-use or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description takes on full responsibility. It discloses that followers receive notifications and lists output fields, but does not explicitly state that the operation is read-only, nor does it mention permissions, rate limits, or pagination. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, front-loaded with the main action, then detailing output and use cases. Every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 parameter, no output schema), the description covers the essential purpose, output structure, and use cases. However, it could mention whether results are paginated or any other behavioral details, but it is nearly complete for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is fully described (100% coverage) for the single parameter 'id'. The description does not add significant meaning beyond the schema's 'Person ID' label, but the baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all followers of a specific person' with a specific verb and resource. It lists the returned fields and provides use cases, effectively distinguishing from sibling tools like persons_add_follower or persons_delete_follower.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes three explicit use cases, which helps an agent understand when to use the tool. However, it does not mention when not to use it or contrast with similar list-followers tools for other entities (e.g., deals_list_followers), leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. Discloses automatic pagination and large dataset risk, but omits potential rate limits, authentication needs, or maximum result size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, then usage guidance, warning, and filter list. However, the filter list is redundant with schema descriptions and could be shortened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 describe return format. It mentions 'returns all products matching filters' but lacks details on ordering, fields returned, or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description repeats filter names and purposes without adding meaningful detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches ALL products automatically via pagination. It distinguishes from sibling tools like products_list (which likely requires manual pagination) by emphasizing automatic handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you need the complete list without managing pagination manually', implying when not to use. Warns about large datasets but does not name specific alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions file types and sorting, but does not disclose read-only nature, error handling, permission requirements, or pagination behavior (start/limit are in schema). The description is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: main purpose, file type examples, sorting info, and use-case bullet list. It front-loads the key action. A minor improvement would be merging the bullet list into a more compact statement, but it's well-organized overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description covers key aspects but lacks details on output structure, error cases, or implicit constraints (e.g., product existence). It is functionally complete for a list tool but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description reiterates sorting fields (id, update_time) that are already in the schema, but adds no new parameter-level details. It does not compensate for missing enums or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all files attached to a specific product,' which is a specific verb and resource. It lists common file types and sorting options, and the product-specific scope distinguishes it from sibling tools like 'files_list' or 'deals_list_files'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Viewing product documentation,' 'Accessing product images,' 'Managing product attachments.' It does not include negative examples or when to use alternative tools, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavior. It notes the return includes complete info and custom fields, but omits any side effects, permissions, or error scenarios. It is not misleading but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and output. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 required parameter, the description adequately explains what it does and what it returns. Minor omissions (e.g., error handling, format of custom fields) keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a description for 'id'. The tool description adds no additional meaning beyond 'Project ID' already present in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details'), the resource ('a specific project'), and the identifier ('by ID'). It also specifies the output scope ('complete project information including custom fields'). This distinguishes it from sibling tools like 'projects_list' which returns a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (when you need full details of a single project), but provides no explicit guidance on when not to use it or alternatives (e.g., for partial data or batch retrieval).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description notes that only 'active' groups are returned and results are ordered by order number. However, no annotations exist, so the description carries full burden; it lacks disclosure on read-only nature, side effects, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding value: first defines action and resource, second provides ordering detail. No redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description is fairly complete: it specifies scope (project), filter (active), and ordering. Minor omission: no hint about the structure of returned groups, but acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id', which is described as 'Project ID'. Description adds no extra semantic meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get all active groups under a specific project', which is a specific verb+resource combination. It distinguishes from sibling tools like projects_get (gets project) and projects_list (lists projects) by focusing on 'groups'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies when to use (when needing groups under a project) but does not explicitly state alternatives or when not to use. No mention of prerequisites or comparisons to other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It mentions that changes affect all activities using this type and that system-defined types cannot be updated, but it lacks details on permissions, idempotency, destructive potential, or side effects. For a mutation tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary, a list of updatable properties, a bulleted 'Workflow tips' section, and a bulleted 'Common use cases' section. Every sentence provides useful information without redundancy, and the most important details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description does not specify the return value format or error handling. However, for a standard update tool with 5 parameters (all optional except id), the description covers the main workflow and constraints. Missing return information and potential error scenarios slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions, and the description adds value by providing example JSON payloads for each parameter and clarifying the color format (6-character hex code without #). Although schema coverage is 100%, the examples and contextual tips enhance understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing activity type' and lists the specific properties that can be updated: name, icon, color, or display order. It distinguishes from sibling tools like activity_types_create or activity_types_delete by focusing on the update action and noting limitations such as system-defined types being immutable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips: use activity_types/list to find the ID first, only include fields to update, cannot update system-defined types, and changes affect all activities. Common use cases with examples are included. However, it does not explicitly state when not to use this tool (e.g., for creating types) or mention alternatives like activity_types_create, though these are implied by the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that followers receive notifications and that duplicates are rejected, but lacks details on auth, rate limits, or idempotency. With no annotations, description carries burden and is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with sections, examples, and tips, though slightly verbose; still effective and front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (2 params, no output schema, no nested objects), description covers purpose, constraints, and common scenarios. Lacks response format but adequate for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no new meaning beyond the schema's field descriptions, earning baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Add a follower to a deal' with specific verb and resource, and distinguishes from siblings like 'deals_remove_follower' and 'persons_add_follower' by focusing on deal followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (use users/list, user must exist, cannot add same follower twice) and examples, but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must cover behavioral traits. It explains the function (returns grouped archived deals) but does not mention safety, side effects, or prerequisites. It implies a read operation, but lacks explicit disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and uses bullet points for workflow tips and examples. However, some bullet points are redundant (e.g., 'Analyze historical deal patterns' and 'Useful for understanding past performance trends'), making it slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 9 parameters, the description provides enough context through examples and tips to understand how to use the tool. It covers common use cases but does not explain response structure, which is acceptable since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds examples that illustrate parameter combinations but does not add significant meaning beyond the schema. The mention of 'same parameters as deals/get_deals_timeline' provides some additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves archived deals grouped by time intervals, with a specific verb 'Get' and resource 'archived deals timeline'. It distinguishes from siblings like deals_list_archived and mentions deals_get_deals_timeline, which provides differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases with example JSON provide context for when to use this tool (historical analysis, seasonal patterns). However, it does not explicitly exclude alternatives or state when not to use it, but the examples guide appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states the destructive action (delete) but does not mention authorization requirements, reversibility, error handling, or any constraints beyond input format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no extraneous information. The first sentence states the purpose, followed by bullet-like format details and a concluding note on normalization. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description covers purpose and input format adequately. However, it omits typical behavioral info (rate limits, success response, error cases) that would be helpful for a destructive operation with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already defines the parameter with a oneOf type and pattern, but the description adds value by clarifying that both comma-separated strings and numeric arrays are accepted and normalized to a query parameter, which helps the agent prepare the input correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Delete multiple custom organization fields in a single request,' clearly stating the verb (delete), resource (custom organization fields), and bulk nature, distinguishing it from the sibling single-delete tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the accepted input formats and normalisation, implying when to use this tool (for bulk deletion), but lacks explicit guidance on when not to use it or alternatives like the single delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses behavior: after removal, the user stops receiving notifications but retains access if permissions allow. It clarifies the tool only affects notification settings, not access rights. This goes beyond basic description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and front-loaded with key information. However, it is slightly verbose; some sentences could be condensed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (delete one entity), and the description covers the effect and use cases. No output schema exists, but the description sufficiently explains the outcome and side effects. It would benefit from mentioning return value (e.g., 'returns success status').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. It restates that 'follower_id' is the user ID, which is already in the schema. A higher score would require additional context like data types or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete a follower from an organization) and explains the consequences. It distinguishes from sibling tools like 'organizations_add_follower' and 'organizations_list_followers', though it doesn't explicitly contrast with 'deals_remove_follower'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists use cases (managing notifications, adjusting team involvement, etc.) but does not explicitly state when not to use this tool or compare it to alternatives like 'organizations_update' or 'deals_remove_follower'. The guidance is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses partial update behavior and explains custom field format in detail. However, it does not mention potential errors (e.g., invalid ID), authorization needs, or side effects. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence for the main purpose followed by three bullet points for custom fields. No redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 17 parameters, no output schema, and nested complexity (custom_fields), the description covers the update behavior and custom fields well but lacks information about return values, validation rules, or examples for other parameters. It is adequate for a simple update but incomplete for a fully informed agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description adds significant value for the custom_fields parameter by explaining how to pass display names vs hash keys and how to handle enum/set fields. This goes beyond the schema's generic 'Custom field values' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update an existing organization' with specific verb and resource. It adds 'Only provided fields will be updated' which distinguishes it from creation or full replacement. Among siblings like organizations_create and organizations_merge, this is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides partial update semantics ('Only provided fields will be updated') but does not explicitly guide when to use this tool versus alternatives like organizations_merge or organizations_add_follower. No when-not or prerequisite conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly indicates a read operation with no destructive side effects and details the returned data categories. However, it does not mention error behavior or pagination (though not expected for a single entity).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence stating the action, followed by a bulleted list of returned data. All sentences are informative, though the list could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 no output schema, the description adequately covers the purpose and the categories of returned data. It does not mention error responses or ID validation, but is complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already describes the 'id' parameter as 'Person ID.' The tool description adds no further semantic meaning beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 about a specific person by ID,' specifying the resource (person) and the key identifier. It lists detailed categories of returned data, distinguishing it from sibling tools like persons_list (list multiple) or persons_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 persons_list or persons_search. The usage is implied by the tool name and description, but no when-not-to or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the operation is read-only ('list'), describes return fields (who, what, when), and mentions pagination. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with bullet points and front-loaded with purpose. Each sentence adds value, though some redundancy exists (e.g., repeating 'changelog' concept).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return fields (field names, old/new values, user, timestamp). It also covers pagination for large datasets. Missing permissions info, but acceptable for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no significant meaning beyond schema parameters (e.g., it mentions cursor-based pagination, which schema already implies).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('updates about person field values'), clearly distinguishing it from sibling tools like persons_list (list persons) and persons_list_updates (general updates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists use cases (auditing, tracking, etc.) but does not explicitly state when to use this tool over alternatives or provide exclusions. It implies usage context but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes it as a read-only listing operation, lists the types of events returned, but does not mention pagination behavior, error handling, or authentication requirements. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an initial summary, a bullet list of included items, and a 'Useful for' section. It is front-loaded with the purpose. Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description explains what the tool returns (list of events). It covers parameters and use cases. Missing details on pagination defaults and error states, but sufficient for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds context for all_changes (not just recent) and items (filter types). This adds meaningful value beyond the schema descriptions, though some parameters like id, start, limit are not further elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists updates about a person (activity stream), and provides a comprehensive list of included events. It distinguishes from sibling tools like deals_list_updates by specifying 'about a person' and providing person-specific examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Useful for' section with use cases, but does not explicitly state when not to use or compare to alternatives like deals_list_updates or organizations_list_updates. Usage is implied but not clearly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description indicates a write operation ('Create') but does not disclose additional behavioral traits such as error conditions, authentication needs, or idempotency. More detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the action and requirements. Every sentence adds value without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and required/optional parameters, but given 13 parameters and no output schema, it could mention return values or validation rules. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a summary of required and optional parameters but does not provide additional context beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new project', which is a specific verb+resource. It distinguishes from sibling tools like projects_get and projects_delete by being the only creation tool for projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (to create a project) and lists required parameters. It does not provide alternatives or when-not-to-use, but the context is clear since there is no other project creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the result is cached for 5 minutes, which is a key behavioral trait. It does not mention authentication, rate limits, or side effects, but for a read-only list operation, this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a one-line summary, a clarifying sentence, caching info, and two example use cases in bullet format. Every sentence adds value, and the structure is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple interface (one optional parameter) and no output schema. The description mentions 'Returns the canonical stage collection via API v2' but does not elaborate on the structure, fields, or pagination. For a list endpoint, agents may need more detail on the response format to process results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description in the schema already states 'Optional pipeline ID filter'. The description adds an example usage and rephrases the filter option, but does not add new semantic depth beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List all pipeline stages across the workspace' with an optional filter by pipeline_id. It distinguishes itself from sibling tools like stages_get and stages_create by specifying the scope ('across the workspace') and the action (list, not single retrieval or creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit common use cases: listing all stages (empty object) and listing stages for a specific pipeline (with pipeline_id). It implies when to use: when you need a collection of stages. However, it does not explicitly state when not to use or compare with alternatives like stages_get_all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions caching for 5 minutes and lists returned fields, but lacks details on authentication, rate limits, or error conditions. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for workflow tips and common use cases. Each sentence adds value, though it could be slightly more concise. Overall, it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains the return value by listing fields and mentioning caching. It covers the essential context for a simple get tool, but could elaborate on potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter and 100% schema description coverage, the baseline is 3. The description adds an example usage but does not provide additional meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific task by ID', which is a specific verb+resource. It distinguishes from sibling tasks_list by noting to use tasks/list to find IDs first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear workflow tip to use tasks/list first and mentions use cases like checking status before updating. However, it does not explicitly state when not to use this tool or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It states the follower stops seeing activities, which adds behavioral context, but does not mention permissions, irreversibility, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, front-loaded with the main action, and adds tips and examples without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers the essential purpose, effect, and a typical use case. Could mention prerequisites like authentication, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds a common use case example but does not significantly enhance meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a follower from a user' and 'Removes the follower relationship between two users,' which is specific and distinct from sibling tools like users_add_follower or users_list_followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips, explicitly suggests using users/list_followers to get follower IDs, and includes a common use case example. Does not explicitly state when not to use, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description discloses caching behavior (10 minutes), inclusion of role hierarchy, and pagination support. This adds valuable behavioral context beyond a generic list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear opening sentence, bullet points for workflow tips, and use case examples. Every sentence contributes meaning without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what the tool returns (role assignments, hierarchy) and highlights caching and pagination. It is sufficiently complete for a list operation, though it could mention error handling or permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (coverage 100%). The description enhances meaning with concrete examples (e.g., listing all roles, paginated list), helping the agent understand parameter usage beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists role assignments for a user and includes workflow tips and use cases. However, it does not explicitly differentiate from sibling tools like roles_get_role_assignments, which may cause ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and use cases provide guidance on when to use the tool (e.g., auditing, pagination). However, it lacks explicit instructions on when not to use it or alternatives, leaving the agent without full context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It discloses that the tool attaches a product with optional pricing, quantity, and discount, and that the product must exist. However, it does not mention error handling, idempotency, or permissions, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, followed by workflow tips and common use cases. It is front-loaded and each section adds value, though the second sentence ('Attaches a product...') is slightly redundant with the first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description covers major use cases but omits details on parameters like product_variation_id and enabled_flag. It does not explain the response structure, and while examples are helpful, they do not cover all scenarios, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's added value is moderate. The workflow tips explain parameter usage (e.g., discount_percentage is 0-100, duration for subscriptions) and the common use cases provide example JSON that clarifies how parameters are combined, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a product to a deal' and elaborates with specific actions like attaching with pricing, quantity, and discount. It includes common use cases that reinforce the purpose and distinguish it from sibling tools like deals_remove_product or deals_update_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips such as using products/search to find product IDs, noting that item_price overrides default, quantity defaults to 1, and discount is a percentage. However, it does not explicitly state when not to use this tool or mention alternative tools like deals_update_product for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses statuses and output lead_id on completion. No annotations, so description carries burden; it adequately describes that it is a polling operation without side effects, but could mention it's read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, efficient use of words. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains possible statuses and successful response includes lead_id. Covers main behavior; minor missing details on errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides clear descriptions for both parameters (100% coverage). Description adds no new semantic information beyond restating usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks status of a deal-to-lead conversion job. Distinguishes from sibling deals_convert_to_lead (starts conversion) and leads_convert_status (lead-to-deal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instruction to use conversion_id from deals_convert_to_lead and lists statuses. Lacks explicit when-not-to-use or alternatives, but context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It warns about large datasets, explains automatic pagination, and notes that add_time_from/until are client-side. However, it does not mention rate limits, authentication needs, or potential side effects beyond data size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for warning, workflow tips, and common use cases. It is front-loaded with the main purpose. However, the workflow tips section could be slightly more concise, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 13 parameters and no output schema, the description covers pagination, filtering, and use cases. However, it lacks information about the response format or structure, which would be helpful for agents to process the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that filters are the same as deals/list, recommending max_items to limit results, and clarifying that date filters are applied client-side. Examples further enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Automatically fetch ALL deals with pagination handling' and distinguishes from sibling 'deals/list' by noting that this tool returns all results in a single response. The verb 'fetch' and resource 'deals' are specific, and the automatic pagination feature is highlighted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes when to use ('Best for exports, reports, or comprehensive analysis'), warns about large datasets, provides common use cases with example filters, and implies not to use for simple queries (use deals/list). It does not explicitly state when not to use, but the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deal value updates automatically, which is a key side effect. However, with no annotations, the description should also cover idempotency, error conditions, or reversibility. The side effect is noted but additional behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with a clear structure: one-line summary, then bullet points for tips and use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal operation, the description covers most aspects: purpose, prerequisites, and side effects. It does not mention the return value or response shape, but since no output schema is provided, this is a minor gap. Overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already has 100% description coverage for both parameters. The description adds value by clarifying that product_attachment_id is not product_id and providing example values, but this is incremental. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a product from a deal, using specific verbs ('Remove', 'Detaches'). It distinguishes itself from siblings like deals_add_product and deals_update_product by focusing solely on removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete workflow tips: use deals/list_products to get product_attachment_id, notes it's different from product_id, and mentions automatic deal value update. Includes example JSON. Lacks explicit 'when not to use' guidance, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It explains partial update semantics, null clearing behavior, custom field handling, and lead-deal custom field inheritance. However, it does not describe the return value or error behavior, which is a gap for a mutation tool with 14 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured with sections: main purpose, custom field notes, workflow tips, and common use cases. It is front-loaded with the verb+resource statement. While informative, it could be slightly more concise without losing key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should provide a complete picture. It covers update behavior, custom fields, and usage tips, but omits information about the response (e.g., whether it returns the updated lead object). For a complex tool with 14 parameters, this missing return value context reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 parameters. The description adds value by explaining null behavior, custom field formats (display names vs. hash keys), and workflow tips like 'Lead ID must be a UUID' and 'value must be an object with amount and currency.' This extra context goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update an existing lead in Pipedrive.' It distinguishes from sibling tools like leads_create and leads_delete by specifying it is for updating existing leads, and provides multiple concrete use cases (title update, value update, archive, clear person).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases that guide the agent on when to use this tool. It explains which fields to include, how to clear optional fields, and gives examples. However, it does not explicitly mention alternatives or when not to use it (e.g., for bulk updates, but no bulk update sibling exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions 'authenticated user' but lacks details on response, idempotency, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main purpose, workflow tips, and common use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a simple create tool with two required parameters. Could mention return value or error handling, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameters fully; description adds example JSON objects but does not add meaning beyond schema's type and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add' and resource 'comment to a note', and differentiates from sibling tools like notes_update_comment and notes_create. It mentions 'threaded discussions', implying hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with examples, but does not explicitly state when not to use or compare to alternatives like notes_update_comment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states 'Modifies the content' indicating mutation, but lacks details on idempotency, permissions, side effects, or return value. The agent is left without information on what the response looks like or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, followed by bullet-style workflow tips and common use cases with JSON examples. Every sentence adds value, and the formatting aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 parameters and no output schema, the description covers the what, required inputs, constraints, and examples. However, it is missing information about return format or error handling, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions, but the description adds value by clarifying that comment_id is a UUID (not a number), that both IDs are required for identification, and that only content is mutable. The provided examples demonstrate real usage, adding practical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool updates an existing comment on a note with the specific verb 'Update'. It distinguishes from sibling tools like notes_add_comment and notes_delete_comment by specifying that only content can be modified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips on required IDs, UUID format, and the constraint that only content can be updated. It references notes_list_comments for finding comment_id, giving clear context for use, but does not explicitly state when not to use this tool (e.g., for adding or deleting comments).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the return fields and implies a read-only operation, but lacks details on authorization, rate limits, or pagination. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, a bullet list of fields, and bullet list of use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description reasonably covers what the tool does and returns. It could mention pagination or permissions, but for a simple read list, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (id) with 100% schema description coverage. The description does not add meaningful information beyond what the schema already provides, maintaining the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all followers of a specific organization, using a specific verb and resource. It distinguishes from sibling tools like deals_list_followers by specifying 'organization'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (checking tracking, auditing access, managing notifications), giving context on when to use. It does not explicitly contrast with other follower list tools, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses automatic pagination, returns all matching persons, and warns about large datasets. With no annotations, this sufficiently covers key behaviors, though rate limits or timeout info is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Clear and well-structured with bullets. Could combine first two sentences but overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers pagination and filters, but lacks output format details or default sorting. Given no output schema, some aspects are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are already documented in input schema (100% coverage). Description merely repeats filters, adding no new semantic meaning beyond grouping as 'same filters as persons_list'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches ALL persons with automatic pagination, distinguishing it from manual pagination tools like persons_list. Verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using when complete list is needed without manual pagination. Implicitly contrasts with persons_list, but lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses array replacement behavior and custom field options. Lacks information on error handling, permissions, or return value. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for required, optional, notes, and custom fields. Every sentence adds value, though slightly verbose. Efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, description covers usage well but omits return value and error conditions. Adequate for an update tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds valuable context: explains replacement for email/phone arrays and two ways to pass custom fields. Additional info beyond schema merits a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update an existing person's information' with specific verb and resource. Lists required and optional fields, distinguishing it from create/get/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance: requires id, only provide fields to change, and notes that email/phone arrays replace existing. Does not explicitly state when not to use or mention alternatives like persons_create but is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details return values: pipeline configuration, stages, deal totals, conversion statistics, stage order/probabilities, rotten deal settings. Good transparency about read-only behavior, though idempotency is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, return info, workflow tips, use cases. Slightly repetitive (e.g., 'Returns pipeline details...' appears early and later), but overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description compensates by listing return components (stages, statistics, settings). Common use cases and parameter examples give practical context. Could be more specific about response structure, but sufficient for a get tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions. Description adds value via workflow tips and explicit examples (e.g., '{"id": 1}' and '{"id": 1, "totals_convert_currency": "USD"}'), going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get detailed information about a specific pipeline' with verb+resource. Lists what is returned: pipeline details, stages, deal statistics. However, does not explicitly differentiate from sibling tools like pipelines_list, pipelines_get_stages, or pipelines_deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description includes 'Workflow tips' and 'Common use cases' with parameter examples (e.g., using totals_convert_currency). Provides context for when to use, but lacks explicit exclusions or guidance on when not to use vs. siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explains how to pass custom fields and provides an example for prices, but does not disclose side effects (e.g., what happens on creation), permission requirements, rate limits, or response format. This is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (intro, required, optional, custom fields, example). It is somewhat verbose but each sentence adds value. No wasted words, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters and no output schema, the description covers all parameters with examples and detailed custom field handling. Missing return value description (e.g., created product object) and behavioral constraints, but overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description significantly adds meaning: explains two methods for custom fields, lists enum values for billing_frequency, provides complete prices array example, and describes each parameter's purpose. This exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new product in Pipedrive.' This is a specific verb+resource combination that distinguishes it from sibling create tools like deals_create or persons_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists required and optional fields but does not explicitly state when to use this tool versus alternatives. It lacks guidance on prerequisites, use cases, or exclusions, relying on implied usage from the entity type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains that the tool returns users based on visibility settings and team structure, and describes visibility options (owner only, team, company, custom). It also notes that access permissions affect product addition to deals. This provides good behavioral context beyond the schema, though it does not explicitly state read-only nature, which is implied by 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, then workflow tips, common use cases, and an example. Every sentence adds value, though it could be slightly more concise. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and no output schema, the description explains the return concept and visibility logic, and includes an example. However, it does not specify the structure of returned users or address pagination/errors. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (id) described as 'Product ID'. The description does not add additional meaning or constraints beyond what the schema provides. Per guidelines, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists users with view/edit access to a specific product. The verb 'list' and resource 'users permitted for product' are clear, and the tool name includes 'products' to differentiate from sibling list_permitted_users tools for deals, organizations, and persons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases (audit, verify, troubleshoot) that help an agent decide when to use this tool. However, it does not explicitly state when not to use it or compare with alternatives like other list_permitted_users tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses filtering (not deleted) and ordering (by order number), which is sufficient for a list tool with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded verb, efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core aspects (scope, ordering) adequately for a simple list tool; could note pagination if applicable, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. Description adds value by explaining the scope and ordering beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'all project boards', and filters 'not deleted', distinguishing it from siblings like projects_boards_get (single board) and projects_list (projects).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no context on prerequisites or exclusions, only describes what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses that only active phases are returned and they are ordered by order number. This adds value beyond the schema but does not cover pagination 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two efficient sentences with no wasted words, front-loading the key action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema), the description provides sufficient context about filtering (active) and ordering, though pagination details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter board_id is 100%, and the description does not add additional meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'active project phases', and the scope 'under a specific board', with ordering by order number. It distinguishes from sibling tools like projects_phases_get or projects_tasks_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing phases under a board but does not explicitly state when to use this tool versus alternatives (e.g., projects_phases_get for a single phase) 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations given; description discloses mutative nature, admin requirement, and consequence (user loses permissions). Suggests using a verification tool. Could mention idempotency or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with title, description, and tips. Concise but could be slightly tighter. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema explanation, error handling details, or synchronization info. Adequate for basic usage but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds example usage but no extra semantic depth beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a role assignment', 'Removes a role from a user') and distinguishes itself from siblings like roles_add_role_assignment and roles_get_role_assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides admin permission requirement and workflow tips (e.g., verify removal), but does not explicitly state when to use vs. alternatives. However, context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies read-only behavior through search semantics and mentions result ordering, but does not explicitly state that it's non-destructive, nor does it disclose rate limits or auth requirements. Additional behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a summary, bullet-point workflow tips, and common use cases. Every sentence adds value without redundancy. It is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool without output schema, the description covers the main functionality and most parameters through examples. However, pagination parameters (start, limit) are not mentioned in the tips or examples, leaving a minor gap for agents needing to handle pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds common use cases that illustrate parameter combinations, but does not provide deeper semantic meaning beyond what the schema already conveys. It matches the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for deals with advanced filtering, and provides specific filtering options (person, org, status) that distinguish it from basic search tools like deals_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips provide clear usage guidance including search term length, filter fields, and status options. Common use cases give practical examples. However, it does not explicitly specify when to use this tool over alternatives like deals_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses 24-hour caching and that it returns a list of add-on codes, but does not detail authentication, rate limits, or side effects. For a read-only list tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long with bullet points and examples, which aids readability. However, some sentences (e.g., 'Add-ons include features like...') could be trimmed without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameters, the description covers the tool's purpose, typical use cases, caching, and response format. It is complete enough for an AI to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter documentation is needed. The description adds context about what add-ons are and response format, which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'get all add-ons for a single company' and lists examples (LeadBooster, Prospector) and use cases. It uniquely identifies the tool's purpose among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases like checking premium features and auditing subscriptions, and mentions caching behavior. However, it lacks explicit guidance on when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains that the tool creates a record and can link to other entities, but does not disclose side effects, rate limits, or specific permissions needed. It is adequate but not highly detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-organized with sections like 'Workflow tips' and 'Common use cases'. The first sentence immediately conveys the purpose. There is minimal redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, no output schema), the description provides examples and tips that cover common scenarios. It could mention expected return values, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the meaning of 'outcome', specifying ISO 8601 format for timestamps, and providing examples. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add a new call log to track phone call activity.' It specifies the verb (create) and resource (call log), and distinguishes from sibling tools like call_logs_list, call_logs_get, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips, lists required fields, and includes common use cases with example JSON objects. It gives clear context but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses caching (1 minute), return fields, and association with other entities. It also implies read-only behavior. This adds value beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, but could be slightly more concise. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers pagination, caching, return fields, and common use cases. No output schema exists, but the description adequately explains the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters (start, limit) with descriptions. The description reinforces the max limit of 50 and provides usage examples, but does not add new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all call logs assigned to the current user' and lists specific fields (duration, outcome, associated records). It distinguishes from sibling tools like call_logs_get and call_logs_create by focusing on listing with pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips and common use cases with JSON examples for pagination. However, it does not specify when not to use this tool or mention alternatives like a search function (which doesn't exist for call logs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions admin-only restriction and required integrations, but lacks details on side effects, idempotency, or error handling. The provided example adds some transparency but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with bullet points and a clear example. It front-loads the purpose and critical constraints, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers input parameters and prerequisites, but lacks information about the response format or what the endpoint returns. Since there is no output schema, this is a notable gap for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by restructuring fields into required/optional lists, clarifying default values, and providing a full example. This goes beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a new messaging channel in Pipedrive', providing a specific verb and resource. It distinguishes itself from sibling tools like channels_delete or channels_receive_message, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states admin-only access and required OAuth scope and manifest, providing clear context for when to use. However, it does not specify when not to use or mention alternative tools, so it's not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It explains soft-delete vs permanent delete, 30-day recovery window, and recommends caution. It does not mention user permissions or rate limits, but covers core behavior adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then structured into workflow tips and use cases. Slightly verbose with examples but every sentence adds value. Could be shorter, but efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single parameter, no output schema, and no annotations, the description covers purpose, behavior, usage, and caution. Missing details on return value or confirmation, but sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the 'ids' parameter with description and minItems. Description adds use cases and example JSON, reinforcing usage. With 100% schema coverage, baseline is 3; description adds marginal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes multiple deals in bulk, distinguishing it from the singular delete tool. It specifies the action (delete), resource (deals), and scope (multiple, bulk).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips: use array of IDs, soft-delete first, permanent after 30 days, caution for bulk effects, and suggests getting IDs via list/search. Common use cases are given. No explicit when-not-to-use, but the caution implies careful consideration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only describes creation parameters and does not mention side effects, permissions, rate limits, or any behavioral traits beyond the act of creating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (Custom fields, Workflow tips, Common use cases) and is mostly efficient. However, it is somewhat lengthy and could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters, only 1 required, no output schema, the description is exceptionally complete. It covers all parameters, provides format hints (dates, currency, probability), and gives multiple example payloads for common scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant value by explaining custom fields (with both display names and hash keys), enum/set fields (use labels), and providing full examples. It greatly enhances understanding beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new deal in Pipedrive' and elaborates on what it does. It distinguishes from sibling tools like deals_update or deals_merge by focusing solely on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips and common use cases, guiding when to use the tool. It references related tools (persons/search, organizations/search, pipelines/list) to get required IDs, but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the copy is exact except ID/timestamps, followers not copied, products copied. This adds important behavioral context. However, does not mention permissions, rate limits, or potential side effects beyond the copy behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Moderately concise with clear sections. Sentences are informative, though some redundancy exists (e.g., first two sentences). Front-loaded with core purpose. Bullet points aid readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description covers behavior, exclusions, workflow tips, and use cases. It is fairly complete for a duplication tool. Could optionally mention return value format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'id' with schema description already at 100% coverage. Description adds example usages and reinforces the meaning, but does not provide significant additional semantic depth beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Duplicate an existing deal' with verb and resource. Distinguishes from siblings like deals_create and deals_update by specifying duplication vs creation/modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, e.g., 'Use deals/get to view the original before duplicating' and 'After duplication, you may want to update the title'. Includes example inputs. Lacks explicit when-not-to-use or alternatives beyond what's implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description covers behavioral traits: mentions response includes person, organization, pipeline, and stage information, and that data is cached for 5 minutes. This adds useful context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for description, workflow tips, and common use cases. Information is front-loaded and concise, though could be slightly more compact without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema), the description covers return content and caching behavior. It is sufficient for an agent to understand what to expect, though error handling or rate limits are not mentioned, which is acceptable for this type of retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description for the single parameter 'id' already states 'ID of the deal to retrieve'. The description includes an example use case 'Get deal details: { "id": 123 }', adding minor value. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get detailed information about a specific deal by ID' and distinguishes from sibling tools like deals_list and deals_search. The description also mentions inclusion of custom fields, reinforcing the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips, such as using deals/search or deals/list to find deal IDs first. Common use cases are listed (e.g., check deal status, retrieve for analysis), giving practical context. Does not explicitly state when not to use, but the tips guide appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the tool returns aggregated statistics, implying a read-only operation. However, it does not explicitly mention that no data is modified, nor does it address potential limitations (e.g., rate limiting, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for workflow tips and common use cases. It is concise enough to convey key information without unnecessary detail. A slight improvement could be combining the tips and use cases into a more compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 optional parameters, no output schema), the description adequately covers what the tool does and what it returns (counts, values, conversion rates). It provides enough context for an AI agent to use it effectively for dashboards and reporting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage with clear parameter definitions. The description adds value by showing common use case combinations (e.g., using user_id and stage_id together), which helps the agent understand how to leverage parameters effectively beyond their individual meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get deal statistics and summary' and specifies aggregated statistics like counts by status, total values, and conversion rates. It distinguishes from sibling tools like deals_list or deals_get by focusing on summary rather than individual deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases with parameter examples, guiding the agent on when to use specific filters (e.g., user_id for user performance, stage_id for pipeline analysis). It covers context but does not explicitly exclude scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns the complete changelog, shows old and new values, includes timestamp and user info, and is cached for 5 minutes. This provides sufficient behavioral insight for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the main purpose in the first sentence, followed by bullet points for clarity. It is slightly lengthy but each section adds useful context; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description covers what to expect (old/new values, timestamps, user info) and mentions caching. It does not explain how this differs from deals_list_updates, but overall it is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters (one: id) with a basic description. The description adds value by providing example usage ('View full changelog: { "id": 123 }') and contextualizing the parameter's role in use cases, beyond just schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists updates (changelog) for deal field values, distinguishing it from other deals tools like deals_list_updates or deals_get. The verb 'list' and resource 'deal field updates' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases (audit trails, compliance, tracking changes), which imply when to use it. However, it does not explicitly state when not to use this tool compared to alternatives like deals_list_updates or deals_get, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behavioral traits: it returns full person details, supports pagination, and is cached for 5 minutes. This adds valuable context beyond the schema, though it could mention potential rate limits or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, making it easy to scan. It is informative without being overly verbose, though the 'Workflow tips' and 'Common use cases' sections have some overlap.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description adequately explains what is returned (full person details) and includes caching behavior. It is sufficient for an agent to use the tool effectively, though adding an explicit return structure would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the baseline is 3. The description adds examples of usage for pagination parameters, which provides context but does not significantly extend beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all persons associated with a deal, including primary contact and participants. It differentiates from the sibling tool 'deals_list_participants' by noting that participants are just person references, making the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, such as pagination and retrieving contact information. It implicitly guides when to use the tool, though it does not explicitly state when not to use it. The differentiation from participants is a strong clue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors (field_type immutable, options replacement semantics) but omits potential side effects, permissions, error states, or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs: purpose, critical note, use cases. No superfluous information. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers inputs and key behaviors but lacks output specification (no output schema) and error conditions. Adequate for a simple update but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with per-parameter descriptions. The description adds behavioral context (field_type cannot be changed, options replacement logic) that is not in the schema, enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing custom product field.' and lists common use cases like rename, add/remove options, toggle visibility. It differentiates from sibling tools like fields_update_deal_field by specifying 'product field'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on handling options (full set with existing ids) and notes that field_type cannot be changed. Does not explicitly contrast with alternatives, but naming and context suffice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes responsibility for behavioral disclosure. It mentions URL expiration, authentication inclusion, and suggests immediate use. This fairly captures the non-destructive, time-sensitive nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (header, workflow tips, use cases). Each sentence adds value, though some redundancy could be trimmed (e.g., 'Get download URL' and 'Returns a temporary download URL'). Still concise overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description covers purpose, behavior, and usage context adequately. No output schema exists, but the return type (temporary URL) is explained. It is sufficiently complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema fully covers the single 'id' parameter. Description adds no extra semantics beyond schema, so baseline is 3. No further parameter guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get download URL for a file' and differentiates from file metadata or content retrieval by emphasizing the temporary download URL. It is specific to the verb 'download' and resource 'file', and distinguishes well from siblings like files_get (metadata) or files_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides helpful workflow tips (URL expires, use immediately, no additional headers needed) and common use cases, but does not explicitly contrast with alternatives or state when not to use. The tips effectively guide the agent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. Mentions file name extraction and max file size dependency, but lacks details on side effects (e.g., overwrite behavior), error handling, or authentication. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with workflow tips and use cases. First sentence conveys purpose efficiently. Slightly lengthy but every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, required parameters, entity associations, file types, and size limits. Lacks output/response specification, but for an upload tool the return value is less critical. Adequate for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining that at least one entity ID (deal_id, person_id, etc.) must be provided, which is not enforced by the schema. Provides examples mapping parameters to use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload a file to Pipedrive and attach it to a deal, person, organization, activity, or product.' It specifies the resource (file) and action (upload and attach) and distinguishes it from sibling file tools (e.g., download, delete) by focusing on upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (full path, at least one entity ID, file name extraction, supported types, max size) and common use cases with JSON examples. Does not explicitly state when not to use, but the context makes it clear for upload scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses caching (15 minutes), return structure (conditions, glue), and that it returns complete configuration. No mention of side effects, but for a read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with main statement, return details, workflow tips, and examples. It is not overly verbose, though some sections could be shortened. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description sufficiently covers return value (conditions structure, configuration). Includes important context like caching duration and relationship to filter list. Completeness is adequate for a simple get tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (id) with 100% schema coverage; description adds an example usage but does not elaborate beyond what schema defines. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a specific filter by ID, describes return details including condition lines, and distinguishes from filters_list by advising to use list to discover IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (use filters/list, caching), but lacks explicit guidance on when not to use this tool versus alternatives. However, the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains custom field behavior (only set values appear) but omits read-only nature, error handling, or response format. Basic transparency but missing safety and side-effect details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise with a clear first sentence, workflow tips, and use cases. Some repetition (e.g., 'Get lead details' example) but overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description explains return includes all fields and custom field values. Tips on custom fields add context. Missing error handling or response format info, but sufficient for a simple 1-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes id as UUID. Description adds value by clarifying that lead IDs are UUIDs (not integers) and provides an example. Schema coverage is 100%, so baseline 3, plus added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a specific lead by UUID, using the verb 'Get' and resource 'lead'. It distinguishes from sibling tools like leads_search and leads_list by emphasizing the UUID-based lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips include using leads/search to find leads by title, and notes on custom fields. While it doesn't explicitly state when not to use this tool, the tips provide useful context. Lacks explicit alternative differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states it creates a link and returns a success message, but lacks details on side effects, permissions, or error handling. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (workflow tips, common use cases) and front-loaded purpose. Slightly verbose but each sentence adds information; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fairly complete given no output schema or annotations. Covers purpose, workflow, parameters, and use cases. Lacks error scenarios and return format, but acceptable for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description reinforces and adds context by listing required fields in a bulleted format with explanatory text, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it links a user with a video call integration and creates a connection between a Pipedrive user and a provider. It uses specific verbs and resources, and implicitly distinguishes from the sibling 'meetings_delete_user_provider_link' by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: must be called after user installs the app, typically by video calling providers. Lists common use cases but does not explicitly exclude alternatives or compare to the delete sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors (e.g., content supports HTML, entity attachment, pinning, user_id, backdating). However, it omits the return value or side effects, which is a gap given the absence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, structured with a one-line summary, workflow tips, and common use cases. Every sentence adds value without unnecessary repetition, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema, no annotations), the description partially compensates by explaining parameters and providing examples. However, it lacks information about the response format or what happens on success, leaving some questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all 11 parameters. The description adds value beyond the schema by explaining usage patterns (e.g., 'At least one entity should be specified', 'Set pinned flags') and providing concrete examples, making parameter semantics clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a new note and attach it to a deal, person, organization, or lead.' It uses a specific verb (create) and resource (note), and distinguishes it from sibling tools like notes_update or notes_delete by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases that illustrate when to use various parameter combinations, such as pinned notes or multi-entity notes. However, it does not explicitly state when not to use this tool versus alternatives like notes_update, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that deletion is permanent and cannot be undone, which is critical behavioral information. However, with no annotations provided, it lacks details on authentication requirements, rate limits, side effects on the note, or the response format (e.g., success/failure status).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement, bullet-pointed workflow tips, and a common use cases section with an example. Every sentence serves a purpose, and the most important information is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, prerequisites, and irreversibility. However, since there is no output schema, it should also explain the return value or success indication after deletion. This omission makes it slightly incomplete for an agent that expects to understand the full response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3, but the description adds value by clarifying that comment_id is a UUID (not a number), providing an example JSON, and stating both parameters are required. This enhances understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a comment from a note' and 'Permanently removes a comment from a note,' specifying the verb (delete) and resource (comment on a note). It distinguishes from sibling tools like notes_add_comment, notes_update_comment, and notes_list_comments by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips including that both note id and comment_id are required, comment_id is a UUID, and to use notes_list_comments to find the comment_id. While it doesn't explicitly state when not to use the tool, the tips and common use cases offer clear guidance on when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that content supports HTML and pin flags exist, but it does not detail whether updates are reversible, what permissions are required, or other side effects. The description adds some context but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, with clear sections for workflow tips and use cases. It avoids unnecessary words, though it could be slightly more structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description covers the main update scenarios through examples. It doesn't document all possible combinations but is sufficient for a typical update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description adds value by showing how parameters interact in examples (e.g., 'Update and pin'), which provides semantic meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing note' and elaborates with specifics: 'Updates note content, entity associations, or pinned status.' This distinguishes it from related tools like notes_create and notes_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (e.g., all fields except id are optional, at least one field must be updated) and common use cases with example JSON. While it doesn't explicitly state when not to use the tool or name alternative tools, the examples guide appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains that results depend on visibility settings, user roles, team assignments, and sharing rules, and lists the fields in each entry. This provides significant behavioral context, but it does not explicitly confirm the operation is read-only (though 'list' implies it) or mention any rate limits or authentication requirements. Still, it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, making it easy to parse. It front-loads the main action. However, it is somewhat lengthy with a list of entry fields and use cases; some sentences could be more concise without losing value. Overall, it is good but not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by listing the fields in each entry and explaining the determination logic. It provides a solid understanding of what the tool returns. However, it lacks details on pagination, ordering, error handling, or limits, which would be useful for complete context. It is mostly complete for a basic list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' (number) with description 'Organization ID', covering 100% of parameters. The description does not add any extra meaning beyond the schema, such as format, range, or typical values. Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing users permitted to access an organization. It specifies the verb 'List' and the resource 'users permitted to access an organization', and distinguishes from sibling tools like organizations_get and organizations_list by focusing on user permissions. The inclusion of details about what determines permission and what each entry contains further clarifies its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, listing use cases such as security auditing and access management. It also notes that results depend on visibility settings, which is useful. However, it does not explicitly state when not to use it or compare it to alternative tools like organizations_get or users_list, which could help an AI agent differentiate among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details what is returned (subjects, timestamps, associated entities) and mentions pagination support, which is sufficient for a read-only list operation. No annotations are provided, so the description carries full burden; it lacks mention of authorization or rate limits but is otherwise transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and front-loaded purpose. It is moderately concise; the use-case list could be shortened without losing meaning, but overall it is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description lists key returned fields and mentions pagination. It does not specify response format (e.g., array or object) or pagination metadata (e.g., total count), which would improve completeness, but the provided information is adequate for an agent to understand and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters (id, start, limit) with 100% coverage. The description adds the word 'pagination' but does not elaborate on parameter formats or constraints beyond the schema, so value added is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List mail messages associated with a person' and enumerates specific email types and data fields, distinguishing it from sibling tools like deals_list_mail_messages or organizations_list_mail_messages by focusing on person context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists practical use cases (e.g., reviewing communication history, preparing for meetings) that guide when to use the tool. However, it does not explicitly contrast with alternative list-mail tools for deals or organizations, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the output includes aggregated data from deals and lists return fields. Does not mention auth or rate limits, but gives sufficient 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is somewhat lengthy but well-structured with bullet points and paragraphs. Front-loads purpose, but could be trimmed slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, description sufficiently explains what is returned and use cases. It is complete for an agent to decide usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. Description does not add extra meaning beyond the schema; parameters are well-documented in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists products associated with a person, specifying it returns product details, deal info, etc. It distinguishes from sibling tools like persons_list_deals by focusing on products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit use cases (e.g., understanding purchase history, cross-selling) but does not mention when not to use or alternatives. Still clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must supply behavioral traits. It does so by detailing intelligent search, fuzzy matching, case-insensitivity, partial matches, ranked results, and a minimum 2-character requirement. It does not describe pagination behavior, but that is covered in the schema. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and clear sections. However, it is somewhat lengthy and could be more concise without losing meaning. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description covers the core search behavior thoroughly. It explains what the search does, the options, and the intelligent matching. Pagination is covered in the schema. It would benefit from mentioning the response format, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 significant meaning beyond the schema: it explains the search options (fuzzy vs exact, field filtering, case-insensitivity) and the behavior of the search engine. This goes beyond mere parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'persons', and the scope (by name, email, phone, or notes). It distinguishes from siblings like search_universal and search_organizations by being person-specific. The detailed explanation of intelligent search features reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (searching persons with various options) and explains search behavior (fuzzy matching, case-insensitive). However, it does not differentiate from the sibling tool 'search_persons', which appears to be an alternative endpoint. This lack of explicit guidance on when to use which reduces clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes the returned statistics in detail, implying a read operation, but does not explicitly state the tool is read-only, require permissions, or mention rate limits. The description adds value but lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (what it does, response includes, workflow tips, common use cases) and is informative without excessive fluff. Slightly lengthy but justified by richness of detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains the response structure (movements_between_stages, new_deals, etc.). It covers all parameters and their usage. It is complete enough for an agent to invoke without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds value by specifying date format requirements, optional user_id behavior, and providing example combinations for common use cases, exceeding the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get deal movement statistics in a pipeline for a specific time period.' It includes a specific verb and resource, and distinguishes itself from siblings like 'pipelines_conversion_statistics' by focusing on movement data such as new/won/lost deals, stage transitions, and deal age.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (date format, user default) and common use cases with JSON examples, guiding when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, though siblings are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks explicit behavioral disclosure such as stating it is read-only or discussing side effects, permissions, or rate limits. Since no annotations are provided, the description carries full burden, but the purpose is straightforward and non-destructive by nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured into two paragraphs: first stating purpose and listing returned data, second giving usage examples. Every sentence adds value, making it efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a comprehensive list of returned data categories, compensating for the absence of an output schema. For a simple get operation with one parameter, this is complete and highly informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single 'id' parameter described as 'Product ID'. The description does not add additional parameter semantics beyond what the schema provides, but it is not necessary. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets detailed information about a specific product and lists the data categories returned. It distinguishes itself from sibling tools like products_list and products_search by focusing on a single product by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (e.g., viewing complete specifications, getting pricing) and implies the tool is for single-product detail retrieval. It does not explicitly mention when not to use it or alternative tools, but the context with sibling tools makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly indicates this is a read-only operation ('Get all deals', 'Returns a list'), with no mention of side effects. The behavioral intent is transparent, though an explicit statement of no mutations would be ideal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and front-loads the main action. It is concise but includes slight redundancy (first two sentences convey similar info). Every sentence adds value, and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description briefly explains what each deal includes ('full deal information plus product attachment details'). It covers filtering and use cases adequately. Could mention pagination behavior or rate limits, but is sufficient for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters. The description adds context for the 'status' parameter by listing its enum values, but does not add new meaning beyond the schema for other parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get all deals where a specific product is attached.' It uses a specific verb ('Get') and resource ('deals'), and implicitly distinguishes from the sibling tool 'deals_list_products' which lists products on a deal (inverse).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases (tracking product usage, analyzing product performance, etc.) and mentions filter options. It implies when to use this tool vs. alternatives, but does not explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully covers behavioral traits: cursor-based pagination, default/max limit, and that templates contain predefined structure. It clearly indicates a read-only operation overall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first line, bullet points, and examples. It is not overly long, though the example partially repeats limit defaults, which is slightly redundant but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool without an output schema, the description adequately covers pagination behavior, template structure, and common use cases. No critical gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (cursor, limit) with 100% coverage. The description adds examples and context but does not provide new semantic meaning beyond what the schema offers, making a baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all project templates with cursor-based pagination', specifying the verb (List), resource (project templates), and pagination method. This distinguishes it from sibling tools like project_templates_get and projects_list, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, explaining when to use templates (e.g., 'standardize project creation') and includes pagination examples. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses caching behavior and response contents (parent role, hierarchy level, assignment counts), adding value beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (Workflow tips, Common use cases). Each sentence adds value, though slightly verbose. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 param and no output schema, description covers workflow and use cases adequately. Could mention error conditions or permissions, but sufficient for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 1 param with description 'ID of the role to retrieve', coverage 100%. Description includes example usage but does not add significant new semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Get' and resource 'role by ID', and details what information is retrieved (hierarchy, assignments, settings). It clearly distinguishes from sibling roles_list which lists roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips: use roles/list to find role IDs, mentions caching (15 minutes). Does not explicitly state when not to use, but implies proper context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the ability to return item IDs via return_item_ids, but does not mention that this is a read-only operation, potential rate limits, or response structure. It is adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, workflow tips, and common use cases. It is concise but includes all necessary details. The examples are helpful without being excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 3 required), the description provides sufficient context through examples and tips. It lacks an explanation of the output format, but the tool likely returns search results consistent with other search endpoints. Overall, it is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are described in the schema. The description adds value by explaining how to use field_key, exact_match, and return_item_ids, and provides concrete examples, surpassing the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches for items by a specific field value, targeting custom or standard fields. It distinguishes itself from siblings like search_deals or search_persons by focusing on field-level search, and provides specific field_type options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips and common use cases with examples, guiding when to use the tool (e.g., searching by custom fields). It implicitly suggests when not to use it (e.g., full-text search not using a specific field). However, it does not explicitly compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions result ordering by relevance, min term length, and default pagination values. Lacks details on authentication, rate limits, or error behavior. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main description, bulleted workflow tips, and code examples. Slight redundancy in opening phrases, but overall front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential usage aspects: search term constraints, filtering options, field selection, pagination defaults, and examples. No output schema, but description doesn't need to explain return values. Lacks pagination limits or error handling, but sufficient for typical search use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters are described in schema, but description adds value with concrete usage examples (e.g., email search, org filter, field selection) that illustrate parameter combinations beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Search for persons' with advanced filtering. Distinguishes from sibling search tools (e.g., deals, organizations) by specifying it's person-specific and includes org_id filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips such as minimum 2-character term, field-specific search, org_id filter, exact_match, and include_fields. Includes common use case examples. However, it does not explicitly state when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the tool returns full configuration and lists fields, but does not mention any permissions, error cases, or side effects. For a simple read operation, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first clearly stating the action and the second listing return fields. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter and no output schema, the description is complete: it specifies the input (stage ID) and the output (full configuration with fields listed).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with one required 'id' parameter described as 'Stage ID'. The description reinforces this but adds no extra semantic detail beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'specific stage by ID', listing the return fields, which distinguishes it from sibling tools like stages_list or stages_get_all that retrieve collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 stage ID and need full configuration, but does not explicitly mention when not to use or compare to alternatives like stages_list for multiple stages. Still, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly explains the operation marks types as deleted/inactive and is a single request. No hidden side effects mentioned, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and structured with a main paragraph and separate workflow tips/common use cases. Could be slightly more concise, but it is well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description fully covers what the tool does, constraints (custom types only), and how to provide input. Examples make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema already describes the 'ids' parameter as comma-separated. Description adds usage examples but does not add significant new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes multiple activity types in bulk, marking them as deleted. It distinguishes itself from single delete (activity_types_delete) and other bulk operations on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips provide explicit instructions: comma-separated IDs, only custom types, efficiency benefit. Common use cases illustrate typical inputs. Does not explicitly compare to alternatives but gives enough context for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses that the call log will be marked with has_recording=true and that the upload is multipart/form-data. However, it does not mention size limits, overwrite behavior, or return value, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (approximately 150 words) and well-structured with sections like 'Workflow tips' and 'Common use cases'. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with no output schema, the description sufficiently explains the effect (has_recording becomes true) and the required parameters. It could mention error conditions or edge cases, but it is adequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 beyond the schema. It provides example values and context (e.g., call log ID, file path) but does not introduce new parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Attach an audio recording file to a call log.' It specifies the verb (attach) and resource (audio file to call log), and distinguishes it from siblings like call_logs_create and call_logs_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips (call log must exist, provide ID and file path, valid audio format, multipart upload) and common use cases with an example. It clearly indicates when to use this tool and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching (5 minutes) and sorting by due date, which adds value beyond the schema. No annotations were provided, so the description carries the burden. However, it does not cover error handling, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with a clear structure: purpose statement, then details, workflow tips, and common use cases. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters with examples, caching, sorting, and result types. While no output schema exists, the description does not detail the response structure (e.g., array of activities), but it is sufficient for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning with examples (e.g., done='0' for pending, comma-separated exclude IDs) and explains the activity types (calls, meetings, tasks, etc.), extending beyond bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all activities associated with a deal.' Identifies the specific resource (deal) and action (listing), distinguishing it from sibling tools like activities_list or activities_list_by_deal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with parameter examples (done, start, limit, exclude). Clearly indicates when to use each filter, though does not explicitly mention when not to use this tool or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it modifies parameters and clarifies 'Cannot change the actual product, only its parameters'. Missing auth needs, idempotency, or error conditions, but adds useful constraint info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with summary, workflow tips, and common use cases. Each sentence adds value; no wasted words. Front-loaded with key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 2 required, and no output schema, description provides sufficient examples and workflow guidance. Missing details on return format or error handling, but overall complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions, but description adds value beyond schema: examples show typical values, workflow tips clarify parameter semantics (e.g., product_attachment_id vs product_id), and that only specified fields are updated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a product attached to a deal', uses a specific verb (Update) and resource, and differentiates from sibling tools like deals_add_product and deals_remove_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips (use deals/list_products for attachment ID, distinguish product_attachment_id from product_id) and common use cases with examples. No explicit when-not, but clear when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It explains normalization of input to query parameter, but lacks information about whether deletion is irreversible, required permissions, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main action, and no unnecessary words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema or annotations, the description is adequate. It could mention that deletion is permanent or require permissions, but overall it covers the essential behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema by explaining accepted formats (comma-separated string or array of numeric IDs) and normalization behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes multiple custom product fields in a single request. It distinguishes from sibling tools like 'fields_delete_product_field' (single delete) and other bulk deletes for different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for bulk operations by saying 'in a single request' and describes accepted input formats. However, it does not explicitly state when to use this versus the single delete tool, or mention when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the delete is soft, values are preserved, and the field stops appearing in UI and new payloads. This is key behavioral information for a delete operation, though it does not cover authorization or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states the action, second explains behavioral implications, third provides an alternative for bulk. No wasted words, front-loaded, and efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers the key points: action, soft-delete behavior, and alternative for bulk. It lacks details on return values or error scenarios, but is sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter description already stating 'ID of the deal field to delete.' The description adds minimal value beyond this, only clarifying that it is a custom deal field. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a custom deal field by ID.' It specifies that it is a soft-delete, preserving values but hiding the field. It also distinguishes from the sibling bulk delete tool by mentioning it is for a single field, providing clear purpose differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs to use `fields_bulk_delete_deal_fields` for deleting multiple fields, offering a clear alternative for batch operations. It does not explicitly state 'when not to use' but implies single vs. bulk usage, providing adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses caching (15 minutes) and returns (field codes, types, options). There is no indication of destructive behavior, and no contradictions with any hidden annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single line and bullet points for common use cases. Every sentence adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers the return data and caching. Sibling tools are many, but the description is specific to project fields, making it complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description adds value by stating what the tool returns and the caching behavior, meeting the baseline. No param details needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets all field definitions for projects, including custom fields, and specifies it's API v2. It distinguishes from other field list tools by specifically targeting projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases like discovering custom fields and checking field types before creating/updating projects, offering clear context on when to use this tool. However, it does not explicitly exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses type immutability and API version, but does not mention authentication, side effects of changing options, or partial vs full update behavior. Adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with action and resource. Every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose and constraints. No output schema, but description is sufficient for basic usage. Lacks details on permissions or return format, but acceptable given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by emphasizing that `field_code` is required, options are for enum/set types, and type cannot be changed. Provides useful constraints beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Update') and resource ('existing project field'), distinguishes from create/delete and other field update tools via entity type. The description specifies what can be updated (name/options) and what cannot (field type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly requires `field_code` and allows any of name/options, with the constraint that field type cannot be changed. Does not explicitly list alternatives (e.g., create or other field updates), but sibling tools make the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description explains the tool creates a link and associates it with an entity, but does not detail permissions, side effects, or error conditions. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections for workflow tips and common use cases. It is concise yet informative, with no unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description covers purpose, parameters, workflow, and examples. It lacks details on error handling or authentication, but is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions. The tool description adds extra value by providing examples and explaining how parameters map to use cases, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a link from remote cloud storage to a Pipedrive entity, listing supported platforms and providing detailed examples. It distinguishes from siblings like files_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips, supported platforms, required parameters, and common use cases. It does not explicitly mention when not to use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description specifies that it returns file metadata including name, size, type, upload info, and associated entities. It doesn't mention side effects (none expected), so it's largely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main sentence followed by 'Workflow tips' and 'Common use cases' sections. Every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, it covers purpose, return metadata, and usage context. Although no output schema exists, the description lists key return fields. Could include error handling, but not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single required parameter 'id', which is already described as 'ID of the file to retrieve'. The description adds minimal extra meaning beyond an example usage, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves detailed information about a specific file, including metadata like name, size, type, associated entities. This distinguishes it from siblings like files_download (downloads file content) and files_list (lists all files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips such as using before downloading and checking associations, and includes common use cases. While it doesn't explicitly say when not to use, the context is sufficient for a simple get tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly indicates a read-only operation but lacks details on pagination, result limits, or response structure. The description does not contradict any annotations (none exist), so no contradiction flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-sentence summary, followed by workflow tips in bullet points, then concrete examples. Every sentence serves a purpose, and the JSON examples make it easy to use. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9 optional parameters and no output schema or annotations, the description covers the main use cases and filtering logic comprehensively. It omits details like default behavior when no filters are applied or pagination, but overall it is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by grouping parameters into common use cases with JSON examples (e.g., filtering by assignee or type). This helps the agent understand how to combine parameters effectively, going beyond the schema's isolated descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all goals with optional filters,' immediately conveying the tool's purpose. It distinguishes from sibling tools like goals_create and goals_delete by specifying it is a retrieval operation. The verb 'Get' and resource 'goals' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases with example filter combinations, guiding when to use each filter. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, such as goals_get_results for more specific result fetching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions 'changes take effect immediately' and implies mutation. Does not disclose return format or validation behavior, but adds some behavioral context beyond no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise but informative: general statement, updatable fields list, workflow tips, common use cases with JSON. Front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (7 params, nested objects, no output schema), description provides enough context with examples and workflow tips. Does not explain return values, but acceptable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, so baseline 3. Description adds value with examples showing structure for nested objects like expected_outcome and assignee, and clarifies usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Update' with resource 'existing goal', lists updatable fields, and provides examples. Differentiates from siblings like goals_create, goals_delete, goals_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (get goal ID via goals/list, update only desired fields, immediate effect) but lacks explicit when-not-to-use or alternatives. Good context for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that leads created via API have source_name 'API' and origin 'API', and that leads share deal custom fields. No annotations are provided, so missing details on rate limits or auth, but reasonable for a create tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections: description, custom fields, workflow tips, and common use cases. Slightly verbose but structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects for a complex create tool with 13 parameters (nested objects). Explains required associations, custom fields, date format, and visibility. Missing output details but acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant value beyond the input schema, e.g., explaining custom fields can use display names or hashes, example payloads, date format, label_ids as UUIDs, and visible_to enum values. Schema coverage is 100%, but the description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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' and specifies that a lead must be linked to a person or organization. It distinguishes from sibling tools like leads_update and deals_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, including required parameters and ID lookup hints. However, it does not explicitly contrast with other creation tools like deals_create, but the context is clear since leads and deals are distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It reveals that the tool returns full note content (potentially HTML), shows associated entities, creator/last editor, and pinned status. This is comprehensive for a read operation, though it does not mention any side effects or authorization requirements (which are minimal for a GET).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, workflow tips, and common use cases. It is slightly repetitive (e.g., 'Returns full note content' appears twice) but overall efficient. The information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description remarkably captures all necessary details: note content, metadata, creator, timestamps, entities, pinned status, and HTML warning. It fully explains what the tool returns and its typical use cases, leaving no gaps for an AI agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (id) and the schema already includes a description ('ID of the note to retrieve') with 100% coverage. The description adds no further meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific note', providing a specific verb and resource. It distinguishes itself from sibling tools like notes_list (which lists notes) and notes_create by focusing on a single note's details. The additional metadata described (creator, timestamps, entities) reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, such as retrieving a note before updating. It gives an example call with { 'id': 123 }. However, it does not explicitly state when not to use this tool versus alternatives (e.g., use notes_list for browsing notes). The guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It outlines the output as a 'comprehensive timeline' and lists event types, but does not disclose pagination behavior, ordering, or rate limits. It is reasonably transparent but could be more detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, bulleted list of content, parameter explanations, and use cases. It is front-loaded and every sentence adds value, earning its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of five parameters and no output schema, the description provides a solid overview of what the tool returns and how to use the parameters. It could mention pagination aspects like start and limit, but overall it's sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context for two parameters (all_changes, items) beyond the schema, explaining their purpose. The remaining three parameters are adequately covered by the schema descriptions, which have 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List updates about an organization (activity stream)' and elaborates on the types of changes included, effectively distinguishing it from sibling tools like organizations_list_activities or organizations_list_field_updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases in the 'Useful for' section and explains the two parameters. However, it does not directly compare to alternatives or specify when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deletion is permanent and cannot be undone, and lists what stays (deals, activities, notes). With no annotations, this is good but lacks information on authorization, rate limits, or response/error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-line purpose, bold warning, and bullet list of unaffected entities. No redundant words, front-loaded with critical info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects for a simple delete tool (irreversibility, side effects). Missing return value or error conditions, but low complexity reduces the need. Adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes 'id' as 'Person ID to delete'. Description adds no extra semantic value beyond the schema; matches baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and resource (person) with a specific verb-noun pair. Distinct from siblings like persons_bulk_delete, persons_create, etc. Includes details about what remains after deletion, reinforcing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use context with a warning about permanence and associated entities. However, it does not explicitly mention alternatives (e.g., bulk delete, soft delete) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool does not delete the image file from storage, only removes the association, and explains the visual outcome. This is valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It uses bullet points for use cases and a separate note for an important clarification. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, no output schema), the description covers the essential aspects: what happens after deletion and what does not happen. It could mention required permissions or error conditions, but these are not critical for core understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a single parameter `id` described as 'Person ID'. The description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete a person's profile picture') and specifies the result (revert to default avatar or initials placeholder). It distinguishes from sibling tools like `persons_add_picture` and `persons_update` by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists specific use cases (updating outdated photos, privacy compliance, data cleanup, resetting profile images), providing context for when to use the tool. However, it does not explicitly mention when not to use it or compare to alternatives like `persons_update`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explains the cursor-based pagination, date range filtering, and benefits over offset pagination. However, it does not mention potential side effects, error handling, or authentication requirements, which would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose, capabilities, differences, parameters, use cases. It is informative but slightly verbose, with some redundancy between the initial bullet list and the later use-case list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain return values beyond 'Get all persons'. It focuses on input behavior but omits response structure (e.g., fields of person objects). For a collection tool, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minor clarifications (default/max limit, date format). It largely reiterates schema descriptions without providing new semantic insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets all persons via a collection endpoint, and explicitly highlights it as an alternative to persons_list with cursor-based pagination and date filtering. It successfully distinguishes the tool from its main sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists specific use cases like initial sync, incremental updates, and large-scale exports. It also explicitly compares with persons_list, detailing key differences (cursor vs. offset, date filtering, performance). This helps the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It lists return fields (activity details, due date, completion status, owner, related deal/organization), which helps the agent understand output. It does not explicitly state safety (e.g., read-only) but 'list' implies no side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening sentence, bullet points of return fields, and separate lines for filters and pagination. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, but the description compensates by listing expected return fields comprehensively. It covers filters and pagination. Missing details like error states or rate limits, but for a simple list operation, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 4 parameters have descriptions). The description adds value beyond the schema by explaining the meaning of the 'done' filter and mentioning pagination parameters implicitly. However, the schema already provides sufficient parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all activities associated with a specific person.' It identifies the resource (person), the action (list activities), and the type of data returned (calls, meetings, tasks, etc.). Among sibling tools like activities_list, deals_list_activities, and organizations_list_activities, this tool uniquely targets person-specific activities, making it easy to distinguish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains filters (done) and pagination, providing context on how to control output. However, it does not explicitly guide when to use this tool over alternatives like activities_list or deals_list_activities. Still, the context is clear enough that an agent can infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full weight. It discloses that the tool returns deals with details like title, value, stage, status, timeline, owner, and organization. It also mentions pagination. It does not reveal potential side effects, but as a read-only list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, using bullet points to highlight return categories and filters. Every sentence adds value, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return values (deal details, timeline, owner, organization) and mentions pagination and filters. It could be improved by noting error conditions or required permissions, but it covers essential usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for each parameter. The description reiterates the 'status' filter and pagination support but does not add new semantic 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all deals associated with a specific person.' It specifies the core action (list) and the resource (deals linked to a person), distinguishing it from sibling tools like deals_list (all deals) or persons_list (list persons).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists available filters (status, sort) and pagination support, providing clear context for when to use the tool. However, it does not explicitly state when not to use it or suggest alternatives, missing a small opportunity for further guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses a side effect (changing deal_probability affects all stages) and states that at least one field must be updated. However, it does not discuss permissions, rate limits, or consequences of deactivating a pipeline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured: a clear opening sentence, bullet-pointed workflow tips, and illustrative examples. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects for an update tool: what fields can be changed, constraints, and usage patterns. However, it lacks information about the return value (e.g., the updated pipeline object), which would improve completeness given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage; description adds value via common use case examples and clarifies that all fields except id are optional. This enhances understanding beyond the schema alone, though not extensively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing pipeline and lists the configurable fields (name, order, active status, probability tracking). It uses specific verbs and resource, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (all fields optional except id, order_nr reordering, active=false deactivation, deal_probability affects all stages) and common use cases with examples. However, it does not explicitly state when to avoid this tool or compare to alternatives like pipelines_create.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses that adding a follower results in notifications for product updates (details, deals, price changes, etc.) and the access requirement. This is comprehensive for a simple creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 5 sentences, well-structured: action, definition, notification details, note. It's concise but could trim redundant phrases like 'This is useful for...' while keeping essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and no output schema, the description is fairly complete. It explains the effect and a key precondition. However, it omits potential edge cases (e.g., what happens if user already follows, error handling for access denial).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of the parameters (product ID and user ID) in the context of follower management, enhancing understanding beyond the schema's simple descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a follower to a product' and explains the purpose of followers (notifications, collaboration). It distinguishes from sibling tools like deals_add_follower by specifying 'product' in both 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (adding followers for notifications) and includes a prerequisite condition: 'Users can only be added as followers if they have access to the product.' While it doesn't explicitly mention when not to use, the context of followers for products is well-established.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Requires admin permissions', and explains that previous assignments are replaced and changes take effect immediately. This is good but could be more detailed about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement, a requirement line, bulleted workflow tips, and a use case example. Each part adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage, no output schema, and simple parameters, the description covers behavior (replacement, immediacy) and prerequisites (admin permissions). It could mention expected responses or errors but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 includes a concrete example ('{ "id": 123, "user_id": 456 }') but adds minimal meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a role assignment', 'Assigns a role'), the target ('to a user'), and distinguishes from sibling tools like roles_delete_role_assignment and roles_list_role_assignments by focusing on adding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (user has one role, replacement, immediate effect) and a common use case example, giving clear guidance on when to use this tool. However, it does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses admin permissions, optional parent role for hierarchy, and that new roles start with default permissions. No annotations provided, so description carries full burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, clear and informative. Could be slightly more concise but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not mention what is returned (e.g., created role object). For a creation tool, return value is important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by noting name uniqueness, optional parent_role_id for hierarchy, and providing example JSON payloads.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Add a new role to the company' with specific verb and resource. Examples differentiate from sibling tools like roles_update or roles_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, including admin permission requirement. Mentions related tool for permissions but lacks explicit 'when not to use' or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers effect (reverts to default value), impact (affects all users with role), and permission requirement. Missing details on idempotency or error handling but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main action, then organized into details. Some repetition (e.g., 'Removes a setting from a role' redundant with title) but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, permissions, behavior, and provides example. References companion tool get_role_settings. Adequate for agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description does not add new semantic meaning beyond schema. The example usage confirms parameter usage but does not explain parameter constraints or behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a role setting', specifies the resource and action. Distinguishes from sibling tools like roles_add_role_setting and roles_update_role_setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, mentions admin permission requirement, suggests checking current settings with get_role_settings. Could explicitly compare with update tool but still helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions caching for 15 minutes and returns all users with pagination. However, it does not describe the response format, error conditions, or rate limits. For a read operation, this is moderately transparent but lacks detail about what user information is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with separate sections for purpose, workflow tips, and common use cases, using bullet points and code examples. It is concise, with no redundant information, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple list endpoint with 3 parameters and no output schema, the description covers purpose, pagination, caching, and use cases. It lacks details on error handling or response format, but is sufficient for basic usage. The completeness is good for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so parameters are already described. The description adds value with common use case examples showing how to use 'start' and 'limit' for pagination, clarifying default values and usage patterns beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets role assignments for a specific role, using the verb 'get' and specifying the resource 'role assignments'. It distinguishes from sibling tools like roles_add_role_assignment, roles_delete_role_assignment, and roles_get_role_settings by focusing on retrieval of users assigned to a role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips including pagination for many users and auditing, and gives common use case examples. It explains when to use pagination but does not explicitly state when not to use this tool or mention alternatives, though the sibling context provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the delete is soft and deals remain pointing to the deleted stage, which are critical behavioral traits. However, it does not mention authorization requirements or other potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences: one for the action and one for key behavioral details. No redundant information, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description adequately covers the action, soft delete nature, and impact on deals. It could mention reversibility or restoration options, but overall it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning beyond the input schema; the schema already describes the 'id' parameter with the same phrasing. The explanation of soft delete behavior relates to the tool's effect but not to additional parameter constraints or formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a stage by ID' and distinguishes from the sibling tool 'stages_delete_multiple' by implying this is for a single stage. It also specifies it's a soft delete, adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about the soft delete behavior and warns that deals are not cascaded, but does not explicitly state when to use this 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool returns stage configuration (order, probability, rotten settings) and pagination info, but does not discuss authentication requirements, rate limits, or error conditions. The read-only nature is implied but not explicit, and the description lacks depth for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an introductory sentence, bulleted workflow tips, and a list of use cases. It is front-loaded with the main purpose but could be more concise by removing redundant examples (two identical 'Get all stages' examples). Overall, it is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, no output schema) and lack of annotations, the description adequately covers functionality, filtering, and return data. It mentions pagination but does not elaborate on pagination parameters or limits. While sufficient for basic usage, it could be more thorough for edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 100% schema coverage with a clear description. The description adds further value by providing usage tips ('omit pipeline_id for all stages') and concrete examples in the common use cases, enhancing the agent's understanding beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves stages, with optional pipeline filtering. It uses specific language ('get all stages across all pipelines or filter by pipeline') and distinguishes from siblings like 'stages_get' and 'stages_create' by emphasizing the 'all stages' scope and filtering capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to omit or include pipeline_id, and lists common use cases with example payloads. However, it does not mention when to avoid this tool or contrast it with alternatives like 'stages_get' or 'stages_list', leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses partial update behavior and reordering, but lacks details on side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short, front-loaded with purpose, and uses examples efficiently. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main use cases for a 7-parameter update tool. Missing output schema details but not critical for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 71% of parameters. Description adds value with examples showing how to use order_nr for reordering and rot rules configuration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Update' and resource 'stage', with specific examples. It distinguishes from sibling tools like stages_create or stages_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to provide only changed fields and includes common use cases. Lacks explicit when-not-to-use but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It explains creation behavior, default value for 'done', and optional fields. It doesn't mention potential response format, permission requirements, or side effects beyond creation. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (workflow tips, common use cases) and includes helpful examples. It is slightly longer than necessary but every part adds value. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema or annotations, the description covers creation intent, defaults, and parameter relationships. It could mention the resulting resource (e.g., returns created task) but is largely complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, but the description adds significant value with workflow tips and concrete examples for common parameter combinations (e.g., project task, subtask, due date). This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a new task') and the resource ('task'). It distinguishes from sibling tools like tasks_delete, tasks_get, tasks_list, and tasks_update by specifying creation. The scope (project or standalone) is also defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, guiding the agent on parameter usage. However, it lacks explicit when-to-use vs alternatives (e.g., vs tasks_update). It implicitly covers creation scenarios well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states 'Update an existing task' and 'Changes take effect immediately', which are clear for a mutation tool. It does not mention permissions, error handling, or side effects, but for a simple update tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~100 words) and well-structured. It starts with a clear purpose sentence, then lists the updatable properties, followed by workflow tips, and ends with common use cases with JSON examples. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does not need to explain return values. It covers what the tool does, which parameters to use, and how to use them with examples. It could mention potential errors or limitations but is largely complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters. The description adds value beyond the schema by providing concrete use case examples (e.g., marking a task as done, reassigning, updating due date) that illustrate how parameters are used together and the expected format (e.g., 'done': 1, 'due_date': 'YYYY-MM-DD').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing task' and lists specific properties that can be updated (subject, description, assignee, due date, completion status). It distinguishes from sibling tools like tasks_create, tasks_delete, tasks_get, and tasks_list by focusing on updating an existing task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips are provided: use tasks/list or tasks/get to find the task ID first, only include fields to update, set done=1 to mark completed, and changes take effect immediately. Common use cases with JSON examples further guide usage. However, it does not explicitly state when not to use or alternatives to exclude.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately conveys that this is a read-only operation returning grouped deal data. It mentions 'Returns open and won deals,' implying no side effects, though it could explicitly state read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, workflow tips, and examples. It is concise yet informative, front-loading the purpose. Clear organization aids agent scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (4 required) and no output schema, the description provides sufficient context through examples and tips. It could elaborate on result format or limitations, but the use cases cover common needs adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 9 parameters (100% coverage). The description adds value by listing common field_key values (add_time, etc.) and providing concrete use cases with example parameter combinations, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get deals timeline grouped by intervals' and explains it returns open and won deals. This distinguishes it from sibling tools like deals_list or deals_get by specifying the temporal grouping aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases with example JSON objects provide clear context for when to use the tool. While it doesn't explicitly state when not to use it, the examples (e.g., monthly forecast, weekly trends) effectively illustrate appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses caching behavior (5-minute cache), pagination support, and that download URLs are included. It also mentions the returned fields (file names, sizes, upload dates). It does not cover rate limits, authentication, or link expiration, but for a read-only list tool 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, workflow tips (bullet points), and common use cases (also bullet points). It is concise and front-loaded with the main purpose. Each section serves a clear function without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately covers the return values (file details, download URLs) and behavioral aspects (pagination, caching). It explains the main use cases and parameters. Minor gaps like authentication requirements or pagination limits do not significantly detract from completeness for this simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by providing example values for the id, start, limit, and sort parameters, including a concrete sort example ('add_time'). It also explains the caching and pagination context beyond what the schema provides. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'list' and resource 'files attached to a deal'. It distinguishes itself from sibling tools like files_list and other deals_list_* tools by explicitly stating it lists files for a specific deal. The description also details what is returned (file names, sizes, upload dates, download URLs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases and example invocations for listing all files, paginated lists, and sorted lists. However, it does not explicitly state when to avoid this tool or mention alternative tools like files_list. The workflow tips imply typical usage but lack explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses caching (5 minutes), dependency on deal visibility settings, and notes that it returns user details and permission levels. This adds value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, workflow tips, and common use cases. It is concise, front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema, no annotations), the description is complete: it covers purpose, usage, behavior, and caching. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (id) with full schema description coverage (100%). The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List permitted users for a deal' and elaborates on what it returns. It distinguishes itself from sibling tools by being specific to deals and user permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, such as checking deal access and auditing access. It gives good context but does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses caching behavior ('Cached for 5 minutes') and hints at output structure (pricing, quantity, totals with discounts). This adds valuable behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, front-loaded with purpose. It is informative but slightly verbose; however, every sentence earns its place by adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description covers return details (products with pricing/quantity, product_attachment_id), caching, and parameter usage examples. It lacks error handling or rate limits, but is sufficient for common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds extra meaning through workflow tips and examples, explaining the role of product_attachment_id, the effect of include_product_data, and default pagination values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all products attached to a deal', specifying the verb (list), resource (products), and context (attached to a deal). This distinguishes it from sibling tools like deals_list or deals_list_activities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Workflow tips' and 'Common use cases' with example JSON calls, guiding when to use the tool and how to leverage parameters like include_product_data and pagination. It implicitly suggests using it before updates/removal via product_attachment_id, though lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses automatic effects: updates close date, triggers notifications and automations, moves to won stage. No contradictions with missing annotations. Could mention idempotency or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, workflow tips, common use cases). Efficient use of sentences with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema), the description covers all necessary aspects: what it does, side effects, verification step, and example use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with schema description; the description adds 'Use deals/get first to verify the deal details' as extra guidance. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks a deal as won, updates status to 'won', and moves to appropriate won stage. It distinguishes from sibling tools like deals_update and deals_mark_as_lost.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, advises using deals/get first for verification, and notes it is more convenient than deals/update. Lacks explicit when-not-to-use guidance but covers key context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses the soft-delete nature, that values are preserved, and the field disappears from UI/payloads. This is good but could mention response or restoration possibilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with action. Every sentence adds value: action, behavioral nuance, and bulk alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-param tool with no output schema, the description covers the essential effect (soft-delete), data impact, and provides a sibling reference. It is fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, so baseline is 3. The description repeats 'by ID' but adds no new meaning beyond the schema's 'ID of the person field to delete'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a custom person field by ID' with a specific verb and resource. It distinguishes from sibling tools by mentioning the bulk delete alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use (delete a single field) and provides an alternative for bulk deletion. It also clarifies the soft-delete behavior, but doesn't explicitly state prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes caching duration (15 minutes) and response contents (field keys, types, validation, options). No annotations provided, so description carries full burden; it does this well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear sections. Slightly verbose but still efficient. Front-loaded with primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description covers purpose, use cases, cache duration, and response structure. Could mention pagination, but not critical for field listing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds value by explaining what the response contains, compensating for lack of output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves field definitions for persons, including custom fields. Distinguishes from sibling field listing tools by specifying 'persons' in the 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this before creating/updating persons to discover fields. Lists common use cases. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that field_type is immutable and that options must be provided as the full set, requiring existing option IDs to preserve options. This explains critical mutation behavior. However, it does not describe side effects on existing deals or return value, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary, a clear note about field_type and options behavior, and a bullet list of common use cases. It is front-loaded with the primary action and wastes no words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description covers the main update scenarios and constraints. However, it omits what the tool returns (e.g., the updated field object), which an agent would need to chain calls. Despite the good annotations within the input schema, the lack of return information leaves a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'options' parameter in terms of preserving existing options with IDs and adding new ones without IDs. It also relates 'add_visible_flag' to a common use case (toggling visibility). This clarifies intent beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('existing custom deal field'). It distinguishes from siblings like fields_create_deal_field and fields_delete_deal_field by specifying 'existing' and focusing on updates. The verb+resource is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit common use cases (rename, add/remove options, toggle visibility) and a key constraint (field_type cannot be changed). It gives clear guidance on how to handle options for enum/set fields. While it does not explicitly name alternatives, the context is sufficient for an agent to infer when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It describes the returned data (current value, target, completion percentage) and implies a read-only operation. It does not mention authentication or rate limits, which is acceptable for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, workflow tips, common use cases. It is slightly verbose but front-loaded with the main purpose. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains the return data (current value, target, completion percentage) and provides example usage. It is complete enough for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds context by explaining that period.start and period.end define the timeframe and providing example date formats. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves progress and results of a goal for a specified period, including current value, target, and completion percentage. It distinguishes from sibling tools like goals_list by focusing on progress data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips are provided: use goals/list to find goal ID, specify period.start and period.end. Common use cases with example JSON are given, but no explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses caching behavior (15 minutes) and mentions response contents (detailed permissions, capabilities). Does not mention any side effects, which is correct for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for workflow tips and use cases. Every sentence adds value, though some slight redundancy between 'Get detailed information' and 'Retrieves complete information'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is quite complete: explains purpose, workflow, caching, and response content. Could be improved with more explicit response structure, but it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is described in the schema as 'ID of the permission set (UUID)'. The description adds value by giving an example UUID and advising to use list to find IDs, which helps the agent understand how to obtain valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific permission set by ID.' It uses a specific verb and resource, and distinguishes from sibling tools like list and get_assignments by mentioning the prerequisite to use list first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips (use list first, response includes contents, cached for 15 minutes) and common use cases with an example. Lacks explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses caching behavior (15-minute cache) and implies a read-only operation; 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and examples, though slightly verbose; front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return content (configurations, assignment counts) sufficiently for a list tool with no output schema; covers key aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the parameter with examples, and the description adds value by showing common use cases and filter context, though schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all permission sets within the company' and specifies the returned information, distinguishing it from sibling tools like permission_sets_get and permission_sets_get_assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with example filters, but does not explicitly mention when to use alternatives like permission_sets_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explains the logic (visibility, roles, teams, sharing rules) and the structure of each entry (user ID, name, email, access level, source). It does not explicitly state that the operation is read-only or mention rate limits, but the behavioral context is detailed enough to understand what the tool does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for what is returned and use cases. It is front-loaded with the main purpose and each sentence adds value without redundancy. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description provides ample context about the return values, logic, and use cases. It adequately addresses what the agent needs to know to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a single parameter 'id' described as 'Person ID'. The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists users permitted to access a person, specifying the resource (person) and action (list permitted users). The title 'persons_list_permitted_users' is unambiguous, and the description provides additional context about what is returned and why.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists use cases (security auditing, access management, etc.) and notes dependency on visibility settings, giving the agent context for when to use the tool. However, it does not explicitly state when not to use it or suggest alternative tools for other entities, but the context provided is sufficient for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that new pipelines start with no stages and need stages added separately, which is useful behavioral context beyond a simple 'create'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main line, workflow tips, and common use cases. It is concise, front-loaded with purpose, and each section adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameter usage and behavioral notes well, but lacks information about return values or response structure. Given no output schema, this omission leaves the AI agent without guidance on what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes parameters. The description adds value with usage examples and tips (e.g., 'active=false to create inactive pipeline'), enriching the meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new pipeline' with a specific verb and resource. Among sibling tools (pipelines_get, pipelines_update, etc.), it is distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, guiding which parameters to use for different scenarios. However, it does not explicitly mention when not to use this tool or compare to alternatives like updating an existing pipeline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses the soft-delete behavior, permanent deletion after 30 days, and the non-propagation to existing deals. This covers key side effects and data retention policies thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the action, and uses clear paragraphs. It could be slightly more structured, but effectively conveys essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers deletion behavior, timeline, and effect on deals. It is largely complete, though it could mention return value or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'id' parameter described as 'Product ID to delete'. The description adds no further semantic detail beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a product, specifies it marks as deleted with a 30-day permanent deletion, and lists use cases. It distinguishes from other product tools and delete tools for other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (discontinuing products, cleaning inventory, removing test products) and notes that deletion does not remove from existing deals, which guides appropriate use. It lacks explicit 'when not to use' but adds sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so description carries full burden. It explains the tool returns a list of users who follow a product and that followers receive notifications. This goes beyond just listing entries, revealing behavioral context about notification management.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficient: one-sentence summary followed by bullet points for response fields and use cases. No wasted text, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully describes parameters and the description covers response fields and use cases, the description is complete for a list tool with no output schema. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add additional meaning beyond what the schema provides for the parameters (id, start, limit). It mentions 'Product ID' in the use cases, but schema already states that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'list', resource 'followers', and scope 'of a specific product'. It distinguishes from similar sibling tools like 'deals_list_followers' and 'organizations_list_followers' by specifying the product context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit use cases (checking who is tracking, auditing, managing notifications). While it doesn't state when not to use or alternatives, the use cases offer clear guidance for typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately discloses behavioral traits: returns relevance-scored results, supports pagination, and searches multiple fields. No destructive behavior is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for features and use cases, and is front-loaded with purpose. A slight redundancy in the features bullet points is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains search behavior, pagination, and relevance scoring. It covers the essential context for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining default searched fields, minimum character requirement, and exact_match usage, beyond what the parameter descriptions provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for products by name, code, or custom fields, and distinguishes from sibling list/get tools by mentioning relevance scoring and multi-field search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes search features and use cases, providing clear context on when to use the tool (e.g., partial name, SKU lookup). However, it does not explicitly state when not to use it or mention alternatives like search_universal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It explains key behavioral traits: full replacement of prices array, optional fields, custom field handling (via display names or hash keys), and enum values for billing_frequency. Lacks mention of authorization needs, rate limits, or response structure, but given no output schema, the coverage is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for updatable fields, notes, and custom fields. It is moderately long but each part adds value. Could be slightly more concise by removing redundant field listing (since schema already lists them), but the clarity benefits from explicit enumeration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, nested objects, and no output schema, the description covers all parameters, explains custom fields and price replacement, and notes optionality. It does not describe return value or error handling, which would enhance completeness. Nevertheless, it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond the schema by listing updatable fields in prose, explaining custom field syntax in two ways, clarifying price replacement, and providing enum options for billing_frequency. This helps an agent understand usage nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing product in Pipedrive' with a specific verb and resource. It lists all updatable fields, distinguishing from create and delete tools among siblings (e.g., products_create, products_delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that all fields except id are optional and to only provide fields to update. It also warns that the entire prices array is replaced. While it doesn't explicitly contrast with other update tools, the context from sibling names makes it clear this is for products. Could mention when to avoid updating (e.g., if creation is needed instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately discloses key behavioral traits: requires admin permissions, changes affect all users with the role, and the format for setting visibility. It also references an article for more information. However, it doesn't detail error handling or whether the update is incremental or full replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement, workflow tips, and common use cases. Every sentence adds value, and there is no redundant information. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the input and effect well, it does not explain the output or return value of the tool. Since there is no output schema, the agent would benefit from knowing what the response contains (e.g., success confirmation, updated role object). This omission leaves some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters (id and visible_pipeline_ids), achieving 100% coverage. The description adds value by giving examples of valid values (1 for visible, 0 for hidden) and demonstrating usage patterns with common use cases. This goes beyond the schema's basic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Update pipeline visibility for a role.' It specifies that it updates visible/hidden status for pipelines and references the sibling tool 'roles/list_role_pipelines' for current visibility, distinguishing 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips on the object format (keys as pipeline IDs, values 1/0), requires admin permissions, and notes that changes affect all users. It also suggests using 'roles/list_role_pipelines' to see current visibility. However, it doesn't explicitly state when not to use this tool or provide alternative tools for other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: minimum 2-character term, field-specific search, exact match option, pagination, and relevance ordering. It does not mention rate limits or authentication, but covers the main operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for workflow tips and common use cases. Every sentence provides useful information without redundancy, and the purpose is front-loaded immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no output schema, the description thoroughly covers input usage but lacks any mention of the output format or default response fields. This is a gap for a tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The description adds value by explaining how to use fields, exact_match, and include_fields with concrete examples, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for products with advanced filtering, and provides specific use cases like searching by name, code, SKU, and exact match. It distinguishes itself from other search tools by specifying product-specific search across all product fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips and common use cases with example JSON, giving clear context on when to use the tool. However, it does not mention when not to use it or suggest alternatives, such as universal search or other entity-specific searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the behavioral disclosure. It explains that the tool returns recent changes, supports filtering by item types, and uses pagination. It does not cover error scenarios or behavior with invalid timestamps, but provides adequate transparency for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for required fields, optional fields, supported types, workflow tips, and common use cases. It is longer than necessary but front-loads the purpose and uses bullet points effectively. Every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameters thoroughly, includes examples, and addresses pagination and filtering. However, it does not describe the response format or return fields, which would be helpful given no output schema. Still, it is largely complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so baseline is 3. The description adds value by explaining timestamp formats, providing examples for each parameter, and clarifying pagination defaults. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves recently viewed or modified items after a given timestamp, distinguishing it from sibling list tools like `activities_list` or `deals_list` which are entity-specific. The verb 'Get' and resource 'recent changes' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains common use cases (tracking activity, syncing data) and provides workflow tips like using pagination and filtering. However, it does not explicitly state when not to use this tool or compare it to alternatives like `search_universal`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses the return format (service name as key, connection ID as value) and that it only returns data for the authorized user. It does not mention any destructive actions or auth requirements, but the read-only nature is inferred.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose with repeated information (e.g., 'Common connections include:' list, 'This is useful for:' list, 'Common use cases:' list). It could be more concise while retaining key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides a complete picture: the tool's purpose, return structure, examples of services, and use cases. It compensates well for missing structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%. The description does not need to add parameter info. Baseline score for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all user connections for the authorized user, specifying the verb 'Get' and the resource 'user connections'. It distinguishes itself from sibling system_* tools by focusing on external service integrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists common use cases such as checking connected services, verifying integration status, debugging, and auditing. However, it does not explicitly mention when not to use this tool or alternatives, though the simple read-only nature makes it low-risk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the operation is permanent ('cannot be undone') and warns about cascading effects on subtasks. This provides good transparency about the destructive nature, though it omits details like required permissions or task state prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, a separate 'Workflow tips' section, and a 'Common use cases' section. It is concise and front-loaded with the main purpose. Minor redundancy ('Delete an existing task' and 'Permanently removes a task') could be merged.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one required param, no output schema, no nested objects), the description covers the essential points: what it does, permanence, side effects on subtasks, and typical usage patterns. It does not describe the return value or authentication requirements, but for a delete operation, these are less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single 'id' parameter, so the baseline is 3. The description adds value beyond the schema by providing concrete usage examples (e.g., { 'id': 123 }) and workflow guidance to retrieve the ID via tasks/list, which helps the agent understand how to construct the call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete an existing task' and 'Permanently removes a task from the system,' with clear verb and resource. It distinguishes from sibling task tools (create, get, list, update) by specifying the delete action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips including using tasks/list to find the ID, noting irreversibility, and potential impact on subtasks. It also gives common use cases with examples. However, it does not explicitly state when not to use or compare to alternatives, though no alternative delete exists for tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions behavioral traits: includes inherited settings, cached for 10 minutes, and role-specific configurations. Since no annotations are provided, the description carries full burden. It does not mention authentication or rate limits, but the caching detail adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear opening sentence. Bullet points structure the information well for quick scanning. Each sentence adds value, though the use cases slightly repeat the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description adequately explains what the tool returns (role settings, inherited, cached). It could mention pagination or limits, but the current level is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'id' parameter as 'ID of the user'. The description adds an example usage and context (e.g., 'Get role settings: { "id": 123 }'). This goes beyond the schema, which is adequate given 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists user role settings. The verb 'List' and resource 'user role settings' are specific. The second sentence 'Returns all role-based settings for the specified user' reinforces the purpose. It distinguishes from siblings like users_list_role_assignments by focusing on settings rather than assignments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases provide clear guidance on when to use the tool, e.g., 'Check visibility and access settings' and 'Review user's role configuration'. However, it does not explicitly state when not to use it or differentiate from similar sibling tools like roles_get_role_settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the creation of custom activity types and their visibility alongside defaults. No annotations provided, so description carries the burden; it is transparent about the operation's effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings, concise sentences, no redundant information. Every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains the purpose and usage well. Lacks description of the return value, but for a simple creation tool, the context is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds concrete examples and format details (e.g., hex without #) that enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Add a new custom activity type' with specific verb and resource. Distinguishes from sibling tools like list, delete, and update by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, guiding the AI on when to use this tool. Lacks explicit when-not scenarios but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses that returns both default and custom types, is cached for 5 minutes, and has an is_custom_flag. This provides adequate transparency for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (core description, workflow tips, common use cases). Every sentence adds value, and the length is appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain the return. It mentions is_custom_flag and general purpose, but lacks a full list of output fields. Still sufficient for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivially 100%. The description adds value by explaining what is retrieved (activity types) and how to distinguish custom from default, meeting the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get all activity types', clearly specifying the action and resource. It distinguishes itself from sibling CRUD tools (create, update, delete) by being a read operation, and it elaborates on what activity types are.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes workflow tips and common use cases, such as populating UI selectors and checking is_custom_flag. It mentions caching behavior. However, it does not explicitly contrast with similar list tools (e.g., activities_list) or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses read-only nature (aggregated stats) and filtering behavior. Does not mention rate limits or auth, but for a summary tool the description 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, followed by bullet points for workflow tips and examples. Slightly verbose but every part adds value; could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains return values (aggregated stats, counts, values, conversion rates) and covers filtering options and use cases. Complete for a summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds value by providing concrete use case examples for each parameter (e.g., 'User archived performance: { "user_id": 123 }'), enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get archived deals statistics and summary' and elaborates on returned data (counts by status, total values, conversion rates). It distinguishes from siblings like deals_get_summary (non-archived) and deals_list_archived (list vs summary) through context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with specific parameter examples, clearly indicating when to use (historical analysis, reporting). Does not explicitly exclude alternatives, but the context of 'archived' and examples suffice for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains that archived deals are removed from active pipelines and describes pagination limits (default 100, max 500). No side effects or destructive actions are involved, so transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear first sentence, explanatory context, and bullet-style workflow tips and examples. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers pagination and filtering adequately for a list endpoint. Lacks explicit return structure, but the presence of sibling deals_list and typical paginated list conventions make up for it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 11 parameters (100% coverage). The description adds value by grouping filters, mentioning compatibility with deals/list, and explaining filter_id usage and pagination limits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists archived deals with pagination and filtering, distinguishing it from related sibling tools like deals_list (active deals) and deals_get_archived_deals_timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips mentioning compatibility with deals/list filters and explicit JSON examples for common use cases. However, it does not explicitly state when to avoid using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by explaining installments are 'scheduled, fixed payments' and a 'modern replacement for legacy subscriptions.' It mentions pagination via limit/cursor implicitly but doesn't explicitly state read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a bold summary, explanatory sentence, and bulleted use cases. No superfluous text; every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description covers purpose, usage, and basic examples. It lacks a description of the response format or pagination details, but overall it's sufficiently complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters described). The description adds value beyond the schema by providing concrete usage examples (e.g., '{"deal_ids": [123]}'), illustrating how to use the required deal_ids parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List installments attached to one or more deals (API v2).' It specifies the verb and resource, distinguishes it from siblings like deals_add_installment, and provides context about installments being scheduled fixed payments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to 'Pass the deal IDs you want installments for' and gives example use cases (single deal, multiple deals). It lacks explicit when-not-to-use or alternative tools, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching (5 minutes), sorting (newest first), and that both sent and received emails are included. No annotations are provided, so the description carries full burden and adds valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with a clear main sentence followed by bullet points for tips and use cases. Every sentence is informative and front-loaded with purpose, making it efficient for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return content (all emails, sorted, cached). It covers pagination and typical use cases, which is sufficient for a list tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description enhances parameters with practical examples (e.g., { 'id': 123 } and { 'id': 123, 'start': 0, 'limit': 50 }) and explains pagination, adding value beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List mail messages associated with a deal' with a specific verb and resource, distinguishing it from sibling tools like persons_list_mail_messages and organizations_list_mail_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with example JSON, including pagination guidance. Does not explicitly exclude alternatives but gives enough context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that results are cached for 5 minutes, paginated, and include deal_participant_id. This is good for a read-only tool, though rate limits and authorization are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, followed by bullet-point workflow tips and common use cases. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description covers key aspects: what it returns, pagination, caching, and practical examples. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the baseline is 3. The description adds value beyond the schema by providing concrete examples of using start and limit for pagination, and clarifying that id is the deal ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all participants of a deal' with a specific verb and resource. It distinguishes from sibling tools like deals_add_participant and deals_remove_participant by mentioning that it returns deal_participant_id needed for removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit examples for common use cases (view all, paginated, before removing) which imply when to use. However, it does not explicitly state when not to use or compare to alternative list tools like deals_list_persons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: status change, lost reason recording, automatic stage move, notifications, and automations. Missing permission details but covers major side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Organized into workflows and use cases; mostly concise with minor redundancy (e.g., repeating 'mark a deal as lost'). Efficient but could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description fully covers all necessary context: effect, usage patterns, common reasons, and pipeline impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds value beyond schema by providing concrete examples, common lost reasons, and emphasizing the importance of lost_reason for analysis.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: marking a deal as lost by updating its status to 'lost'. It differentiates from siblings like deals_update and deals_mark_as_won by highlighting convenience and specific outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, including explaining when to use this tool over deals_update. Offers common lost reasons but lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses case-insensitivity, minimum 2 characters, exact_match option, caching for 5 minutes, and pagination. No annotations exist, so description carries full burden and does it well, though error handling is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Intro + bullet points for workflow tips and use cases. No fluff, every sentence adds value. Well-organized and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all major aspects for search tool: parameters, examples, performance, caching. Lacks output schema/return format, but pagination and field filtering are addressed. Sufficient for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, but description adds examples and defaults (e.g., fields default 'all', status filter values). Explains behavior like caching and case-insensitivity beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search for deals using a text query' and specifies searched fields (title, notes, custom fields). Distinguishes from sibling tools by noting it is 'Much faster than filtering all deals.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips, common use cases, and parameters for filtering. Explicitly mentions performance advantage over listing all deals, but does not list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must bear full burden. Reveals that after creation, the field's key is the hash for payloads. Also discloses 15-minute cache delay. These are important behavioral traits that go 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-structured: starts with main purpose, then specific requirements, common use cases, and post-creation behavior. No unnecessary words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations, but description covers creation flow: requirements, use cases, and post-creation (key, caching). Could mention error conditions or permissions, but for a straightforward creation tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. Description adds value by explaining the options format ({ label } objects) and the consequence of creation (key usage). This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new custom field for deals' with specific verb and resource. It provides common use cases (dropdown, monetary, date) which reinforces the purpose. Differentiates from sibling tools like fields_create_organization_field by specifying 'deals'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states requirement for enum/set types to provide options. Provides common use cases as guidance. Mentions caching delay and need to call fields_list_deal_fields to see reflection. Lacks explicit alternatives, but domain distinction with siblings is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behaviors: caching for 15 minutes, that the field key is a hash used in other payloads, and required options for enum/set. It does not mention permissions, error handling, or maximum lengths, but for a create tool, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: purpose, constraints, use cases, and post-creation behavior are clearly separated. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, 2 required, no output schema) and the provided sibling context, the description covers all essential aspects: required inputs, behavioral nuances (caching, key usage), and typical scenarios. It does not explain return values but that is acceptable for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by explaining the options parameter requirement for enum/set, providing use case examples for different field types, and linking the result to the key used in other operations. This goes beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool creates a new custom field for organizations. Examples of use cases further clarify the purpose, and it is easily distinguishable from sibling tools like fields_delete_organization_field or fields_list_organization_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool by listing common use cases and specifying constraints for enum/set types. It also suggests calling fields_list_organization_fields after a delay to see results. However, it does not explicitly compare to alternatives like fields_update_organization_field or give 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the 15-minute cache, the need to use the field's key in product payloads, and option requirements. This is sufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first sentence states purpose, then parameter-specific notes, then use cases, then post-creation behavior. Every sentence adds value, and it is front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, 100% schema coverage, no output schema, and no annotations, the description covers creation requirements, caching, and verification steps. It is complete enough for an agent to use correctly, though return value is not specified (acceptable for a creation tool).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the options requirement for enum/set, providing use case examples, and noting the field's key usage after creation. This justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new custom field for products.' This specific verb+resource+scope distinguishes it from sibling tools like fields_create_deal_field, as it targets product fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases, requirements for enum/set types, and mentions the caching delay with the need to call fields_list_product_fields to verify. It does not explicitly exclude alternatives but gives clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the dependency on options for enum/set types and the reuse of field_code for future operations. It does not mention auth or rate limits, but for a creation tool this is adequate behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second adds essential usage detail. Front-loaded, no redundancy, every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 imply return structure. Mentioning field_code hints at the response containing it. The tool's simplicity (3 params, 2 required) means minimal expectations; completeness is adequate for a basic creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 3 parameters described). The description adds behavioral context beyond schema: options must be non-empty label arrays for enum/set, and field_code is used for updates. This enhances understanding of how parameters relate to tool behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'new custom field for projects (API v2)', distinguishing it from sibling tools like fields_create_deal_field. The resource scope is explicitly 'for projects', 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides specific usage guidelines: enum/set fields require options with label objects, and the resulting field_code is used for later updates/deletes. It does not explicitly state when to use vs alternatives, but the naming convention with siblings (project vs deal vs person) makes it obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses caching behavior (15 minutes) and search scope across names and keys. Could mention response pagination or limits for completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for scope, results, and common uses. It is concise yet comprehensive, earning its sentences without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains result fields (entity type, ID, key, name, type, validation). It could mention whether results are paginated or limited, but overall is sufficient for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. The description adds value by providing example queries and explaining partial key matching, which enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for fields by name or key across entity types.' It uses specific verbs and resources, distinguishing itself from sibling tools like fields_list_all_fields and search_by_field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes common use cases and examples, such as finding a field by name or searching in a specific entity. However, it does not explicitly state when to avoid 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses key behaviors: field_type cannot be changed, options represent the full set after update with id preservation semantics, and lists common modifications. Doesn't mention side effects on existing data or authorization, but adequately covers the tool's mutational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: brief purpose statement, a note with critical behavior, and bullet-pointed common use cases. Front-loaded with essential information, no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers core aspects: field_type constraint, options handling, and common use cases. Lacks return value description but is sufficient for selection and basic invocation. Adequately complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value beyond schema by explaining the options replacement behavior and providing common use cases that inform parameter usage. The note about including existing option ids to preserve them is not in the schema, enhancing semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update an existing custom organization field' with specific verb and resource. Lists common use cases such as renaming a field, adding/removing options, and toggling visibility, which further clarifies purpose and distinguishes it from sibling tools like fields_create_organization_field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (updating existing fields) and important constraints like field_type immutability. Implicitly distinguishes from create/delete siblings through common use cases, but lacks explicit 'when not to use' or direct alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly states deletion is permanent and cannot be undone, and that all specified filters are deleted in one call. Lacks details on error handling (e.g., invalid IDs) or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with concise sections: purpose, efficiency, workflow tips, common use cases. No wasted words, front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple bulk delete tool with one parameter and no output schema, description covers purpose, usage, and permanence. Missing details on error handling or return values, but complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by specifying format (comma-separated string), providing examples, and common use cases, going beyond the schema's basic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes multiple filters at once, using specific verb 'delete' and resource 'multiple filters'. It distinguishes from the sibling tool 'filters_delete' by highlighting bulk operation and efficiency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips, including when to use (bulk delete for efficiency) and how to get filter IDs via filters/list. However, it does not explicitly mention when not to use, such as for single filter deletion (use filters_delete instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses important limitations: only one first-level condition group, two second-level groups, max 16 conditions, required glue constraints. Mentions return value (filter ID).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (limitations, workflow tips, example). Front-loaded with main action. Length is justified by complexity; no unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a creation tool with nested conditions. Covers all structural constraints, provides example, references external tools for discovery. No output schema but return value noted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, description adds significant value by explaining the conditions structure, providing an example, listing common operators and filter types, and referencing helpers for field IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Create' with specific resource 'new filter in Pipedrive'. Distinguishes from sibling tools like filters_get, filters_list, filters_update by focusing on creation. Returns filter ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips referencing filters/helpers for field discovery, lists permitted filter types and operators, and outlines limitations. Does not explicitly state when not to use, but offers sufficient contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries burden. Details important limitations: condition group structure, max conditions. Notes that only provided fields change. Missing authentication/rate limits, but acceptable for an update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded purpose. Slightly verbose, but justified by complexity and examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity of conditions, description is thorough: limitations, workflow tips, examples. No output schema, but update tools typically return updated object; not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds value: explains conditions structure, common operators, examples. More than baseline needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update an existing filter in Pipedrive.' Specifies the resource (filter) and action (update). Distinguishes from siblings by focusing on update vs create/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when to use: updating filter name/conditions. Provides workflow tips (use filters/get, filters/helpers) and lists limitations. Does not state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses destructive nature and side effects (report deletion). Lacks permission requirements, but still transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Moderate length with clear structure: intro, side effect, workflow tips, common use cases. Each sentence serves a purpose, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description covers all necessary aspects: purpose, side effects, usage tips, and examples. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id'. Description adds an example and tips for obtaining the ID, but does not add new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a goal and that associated reports are also deleted. Distinguishes from sibling tools like goals_create, goals_update, and goals_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides actionable workflow tips: use goals/list to find the ID, warns about irreversibility and cascading deletion of reports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is a wrapper with narrower OAuth scope and mentions result_score for relevance. No annotations exist, so description carries full burden. It implies read-only behavior through 'search' but could explicitly state non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a brief summary, followed by workflow tips and common use case examples. Every sentence adds value and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers pagination, filtering, exact match, and field selection. Lacks explanation of output format but no output schema exists. Adequately complete for a search tool with 8 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers 100% parameter descriptions (baseline 3). Description adds value beyond schema with workflow tips like minimum 2 characters for term, max 2000 leads for filters, and default fields behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search leads by title, notes, and custom fields' and specifies it is a wrapper of /v1/itemSearch with narrower OAuth scope. This differentiates it from sibling tools like deals_search or universal search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed workflow tips including minimum character requirements, exact_match behavior, filtering by person_id/organization_id, fields selection, and pagination. Includes common use cases with example JSON. However, it does not explicitly compare to alternative lead tools like leads_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that deletion is immediate and irreversible, and that re-linking is required. It does not mention permission requirements or potential side effects, but for a simple link deletion, the transparency is good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Required fields, Workflow tips, Common use cases). It is concise but could be slightly tighter; however, it efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers purpose, required field, usage tips, irreversibility, and re-linking. It provides an example UUID, making it complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the 'id' parameter 100%. The description adds meaning by specifying it is a UUID and that it matches the user_provider_id used when creating the link, which provides useful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a link between a user and a video call integration, using specific verbs and resources. It distinguishes itself from the sibling tool 'meetings_link_user_provider' by being the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips (e.g., when to use, ID same as creation, immediate/irreversible) and common use cases. It lacks explicit guidance on when not to use, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses pagination behavior, chronological ordering, and that comments include author info and timestamps. It implies a safe read operation without side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with a clear opening sentence followed by bullet points for workflow and use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers behavior (pagination, order) and mentions that comments include author info and timestamps. It is sufficiently complete for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining default limit (100) and max (500), and provides concrete examples. This goes beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all comments for a note' using a specific verb and resource. It distinguishes itself from sibling tools like notes_add_comment, notes_delete_comment by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips for pagination with default and max limits, and common use cases with example parameter values. While it doesn't explicitly say when not to use, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description compensates by disclosing key behaviors: it provides a caching duration of 15 minutes and confirms pagination support. It implies read-only operation but does not explicitly state it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence summary, followed by bulleted workflow tips and common use cases. No redundant text; every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with 3 parameters and no output schema, the description covers purpose, usage tips, caching, and pagination. It could mention the structure of returned data but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters, but the description adds value with concrete usage examples (e.g., { 'id': '...', 'start': 0, 'limit': 50 }). This helps users understand how to apply the parameters in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves permission set assignments, specifying the action (get) and resource (permission set assignments). This distinguishes it from sibling tools like permission_sets_get (fetches a permission set) and permission_sets_list (lists all permission sets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips like 'Shows all users with this permission set' and 'Use pagination for permission sets with many users', along with common use cases and example JSON. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that followers receive notifications about various updates (details, activities, deals, notes). Mentions access requirement. No annotations provided, so description carries the burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, then bulleted list of notification events. No unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, constraints, and notifications. Lacks mention of return value or idempotency, but adequate for a simple add operation without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions, but description adds meaning: user_id must have access to the person. Provides context about follower behavior beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Add a follower to a person' and defines followers as users who receive notifications. Distinguishes from similar sibling tools like deals_add_follower by specifying the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use (for team collaboration and keeping stakeholders informed) and includes a constraint: users must have access. Does not explicitly exclude scenarios, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavioral traits: how the image is displayed, requirements (format, size, file size), optional cropping, and workflow. It is transparent about what the tool does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (image display, requirements, cropping, workflow, use cases). It is detailed but not overly verbose, with each section adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description does not mention return values or error handling. It covers image requirements and usage well, but fails to describe what the tool returns (e.g., success message, picture URL) or potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining cropping in pixels, file format requirements, and workflow steps that contextualize parameters like file, filename, and crop_*.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add or update a person's profile picture,' using a specific verb and resource. It distinguishes from sibling tool persons_delete_picture by focusing on adding/updating, not deleting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow steps, image requirements, and use cases (e.g., adding profile photos, updating images). It gives clear guidance on when to use, though it could explicitly mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses irreversibility, data deleted (custom fields, notes, follow relationships), activity handling, rate limits, and permission requirements. Comprehensive for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and warnings. Length is justified by complexity of bulk deletion, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, side effects (what is deleted), best practices, and rate limits. No output schema, but description explains return behavior adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description mostly restates schema (comma-separated IDs). Adds example and usage context, but does not significantly enhance meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete multiple persons in bulk' and lists specific use cases (data cleanup, duplicates, GDPR). Distinguishes from sibling tools like persons_delete by specifying bulk operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit best practices (verify IDs, backup, check deals, permissions) and warnings (irreversible, rate limits). Implies when to use but does not explicitly exclude alternative single-delete tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns conversion rates with specific fields (stage_conversions, won_conversion, lost_conversion) and defaults to the authorized user. It lacks explicit mention of being read-only but is implied. No annotations exist to contradict or supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear sections (purpose, output, workflow tips, use cases) and is front-loaded with the main purpose. Some redundancy exists, but it remains readable and efficiently conveys information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the response structure. All parameters are addressed, and the common use cases illustrate typical invocations. The tool's purpose and context within the pipeline family are well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds value by specifying date format (YYYY-MM-DD), the default behavior of user_id, and providing example JSON objects in common use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves conversion rates for a pipeline over a time period, with specific verb 'Get' and resource 'pipeline'. It differentiates from siblings like 'pipelines_movement_statistics' by focusing on conversion rates rather than movement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases provide guidance on when to use the tool, such as analyzing pipeline efficiency and tracking improvements. However, it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that stages are returned in order (by order_nr), includes deal probability and rotten deal settings, which are behavioral traits. It does not mention auth requirements or side effects, but for a read-only operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections: main description, workflow tips, and common use cases. It is concise without being terse, though a few sentences could be more directly actionable. The structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description fully covers the return details (ordered stages, probability, rotten settings) and provides concrete examples. There are no gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id' (pipeline ID). The description adds value by showing how to use the parameter in context (e.g., 'Use this to get stage IDs for deal creation'), which goes beyond the bare schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'all stages for a specific pipeline', distinguishing it from sibling tools like pipelines_get (which gets pipeline details) and pipelines_deals. It specifies the output includes configuration, order, probability, and rotten settings, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, such as obtaining stage IDs for deal creation and checking stage probabilities. While it does not explicitly state when not to use, the examples offer clear context for appropriate scenarios, e.g., retrieving all stages rather than a single stage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It covers return content (pipelines, stages, active/inactive, order_nr, deal_probability). Lacks authentication, rate limits, or pagination info, but adequate for a read-only list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: summary, workflow tips, common use cases. Every sentence adds value without redundancy. Concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completeness is good given no output schema and zero parameters. Explains what is returned and common uses. Could mention response format or limits, but sufficient for a simple list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%), so the description adds meaning by explaining returned fields and workflow value. Exceeds baseline by clarifying fields like order_nr and deal_probability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all pipelines and includes their stages. It distinguishes from siblings like pipelines_get (single pipeline) and pipelines_create by being a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases explicitly guide when to use, e.g., getting pipeline IDs, checking stages, verifying configuration. However, it does not explicitly state when not to use (e.g., for a single pipeline).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching behavior (15 minutes), pagination support, and returned data (hierarchy, assignment counts). No annotations provided, so description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with bullet points. Front-loaded with clear purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers pagination, caching, and returned data. No output schema, but description adequately sets expectations for a simple list tool. Could mention rate limits but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with parameters for pagination described in the schema. Description mentions use cases with example values but does not add significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all roles within the company, with a specific verb and resource. It distinguishes itself from sibling tools like roles_create or roles_add_role_assignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, including pagination and caching. Does not explicitly exclude alternatives but offers clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions a 15-minute cache, which is important for agents to know about data freshness. No annotations are provided, so the description carries the burden for behavioral traits. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, followed by workflow tips and common use cases. It is concise, front-loaded, and each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return type (all pipelines with visibility status) and caching behavior. It does not detail the exact structure of the response, but for a list tool, this is sufficient given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions, and the description reinforces their use with examples, such as filtering by 'visible'. This adds practical guidance beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'pipeline visibility for a role'. It specifies the scope (specific role) and distinguishes from sibling tools like roles_get or roles_update_role_pipelines, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases, including how to use the 'visible' parameter for filtering. However, it does not explicitly state when not to use this tool or compare with alternatives like roles_get_role_assignments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description confirms non-cached, real-time data and enumerates all returned fields. Safe read operation is implicit. Sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and sections, but slightly verbose. Front-loads purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely describes return values, use cases, and caching behavior. No gaps given zero parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 per instructions. Description adds no param info but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets performance metrics for the MCP server, lists specific metrics and use cases, and is distinct from all sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use cases (monitoring, debugging, analysis) and mentions 'Metrics are always fresh' for real-time. Lacks explicit negative guidance or alternatives, but unnecessary given no sibling overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses caching behavior (1 hour) and response format. No annotations are provided, so it carries full burden, but it omits any side effects or permission requirements. Still, it gives useful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, and the main purpose is front-loaded. However, it is somewhat verbose with a long list of settings and use cases; some redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description fully explains the response format (key-value pairs, types) and includes caching details and common settings. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. Description adds no parameter info, but none is needed. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists settings for the authorized user, using specific verb 'List' and resource 'settings'. It distinguishes from sibling tools like system_get_current_user and system_get_metrics by focusing on configuration settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists common use cases and scenarios for using the tool, such as understanding user preferences and checking feature access. However, it lacks explicit guidance on when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It thoroughly explains the action (clear all cache), the consequences (forces fresh API requests, temporary performance impact), the return value (number of cleared entries, with response fields), and provides caution. This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main sentence, bullet points for use cases, a caution, and response details. It is somewhat long but every sentence adds value. It front-loads the core action, making it efficient for scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains return values (message, previousSize, timestamp). It also covers use cases, caution, and the nature of the operation. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and schema description coverage is 100% (trivially). The description does not add parameter semantics because none exist. According to the rubric, when coverage is high, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Clear all cached data from the MCP server,' providing a specific verb ('Clear') and resource ('cached data'). It distinguishes itself from sibling tools, which focus on CRUD operations for entities like activities, deals, etc., by being the only cache management tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('Debugging cache-related issues', 'Forcing refresh of stale data', etc.) and includes a CAUTION about performance impact. It does not mention when not to use it, but the context is clear enough for an AI agent to decide appropriately, given no alternative for cache reset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses need for admin permissions, activation email sending, default active status, and that name can be derived from email. Does not mention rate limits or billing impact, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose, admin note, bulleted workflow tips, and example use cases. Every sentence adds value, and the format is easy to scan. No redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers creation behavior, constraints, and typical usage patterns. Lacks details on return value or error cases, but for a tool with no output schema and clear parameters, this is sufficient. Could mention response includes user object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; each parameter has a description. The description adds value by noting email uniqueness requirement, derivation of name from email, and providing example JSON objects, which enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Add a new user to the company' and 'Creates a new user account in the Pipedrive company', distinguishing it from sibling tools like users_update or users_get. The verb-resource pair is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (email uniqueness, activation email, default active, name derivation) and common use cases with examples. Does not explicitly mention when not to use or alternatives, but the context is sufficient for a create operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It adds useful behavioral info: caching for 10 minutes, and what fields are returned (roles, permissions, timezone, access settings). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet structured: clear core statement, followed by workflow tips and common use cases. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single parameter and no output schema, description explains response contents (roles, permissions, etc.) and caching behavior. Missing error handling or full field list, but adequate for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value with an example JSON snippet for the id parameter, helping the agent understand usage format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get detailed information about a specific user by ID', using a specific verb and resource. It distinguishes from sibling tools like users/list and users_get_current by focusing on a single user with ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips, including using users/list to find IDs first, and lists common use cases. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching for 10 minutes, which is a notable behavioral trait. Without annotations, it adequately covers the tool's read-only nature and output details. Minor gaps on error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with a clear opening, bullet-point workflow tips, and common use cases. Every sentence contributes meaningfully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with no output schema, the description provides adequate information on return content (permissions, role, access levels) and caching. Lacks full field list but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so the description correctly notes 'No parameters needed'. It adds value by explaining what the tool returns, compensating for the lack of schema parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get information about the current authorized user' with a specific verb and resource. It distinguishes from sibling tools like 'users_get' by emphasizing the current user and API token association.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, including when to check permissions or verify the API token. Implicitly tells when to use vs other user tools, though lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: returns all users (no pagination), includes active and inactive users, shows roles/permissions, and is cached for 10 minutes. This adequately informs the agent about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (workflow tips, common use cases), though it is slightly verbose. Each sentence adds value, but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully explains the tool's purpose, behavior, and return content. It covers caching, user status inclusion, and common use cases, making it complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description adds value by explaining what data is returned (roles, permissions, access levels), which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'users', and specifies 'all users within the company', differentiating it from tools like users_find (search) and users_get (single user).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (no pagination, includes active/inactive, caching) and common use cases, giving clear context for when to use this tool, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching (5 min) and that response includes has_recording. With no annotations, it provides good behavioral context for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with main description, workflow tips, and common use cases with example. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with no output schema, the description explains return fields (phone numbers, duration, outcome, linked records, has_recording) sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a simple id parameter. The description adds the workflow advice to find ID via list and gives an example ID format, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific call log by ID' and lists the information retrieved (phone numbers, duration, outcome, linked records). It distinguishes from call_logs_list by implying this retrieves a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips explicitly tell to use call_logs/list to find IDs first, mention caching, and provide common use cases. No explicit when-not-to-use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses permanent deletion, required scopes/manifest, and provides a required field with example. Lacks rate limits or error details but sufficient for a deletion action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose sentence, requirements, warning, required fields, and example. Each sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-parameter, no-output-schema tool, the description covers purpose, prerequisites, irreversibility, and parameter details comprehensively. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id' described. Description adds an integration-specific phrase and a concrete example, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an existing messenger's channel and all related entities (conversations and messages)', specifying the verb (delete) and resource (channel) with scope. Among sibling tools (channels_create, channels_delete_conversation), it is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies required OAuth scope and Messaging manifest, and warns about irreversibility. However, it does not explicitly contrast with alternatives like channels_delete_conversation, though this is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It clearly states that the action cannot be undone and that all messages are permanently deleted, along with required prerequisites. This exceeds expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: purpose first, then prerequisites, warnings, required fields, and an example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with two parameters and no output schema, the description covers all necessary information: prerequisites, behavior, irreversibility, and parameter examples. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description lists required fields and includes an example, but adds minimal 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an existing conversation from a channel,' providing a specific verb and resource. It distinguishes from sibling tools like channels_delete (which deletes the channel itself) and other conversation-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes required OAuth scope and Manifest readiness, and warns that the action is irreversible. It does not explicitly contrast with alternatives but provides sufficient context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses the asynchronous behavior, the two-step flow, the response structure, and the side effect of transferring related entities. This adds significant value beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear steps, no redundant information, and each sentence adds value. It efficiently conveys the asynchronous flow and follow-up action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the expected response format for both steps and the polling criteria. It also mentions the transfer of related entities, making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (id). The description adds minimal extra meaning beyond the schema's description ('Deal ID to convert'). It is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: convert a deal into a lead. It distinguishes this tool from sibling tools by naming the specific polling tool (deals_convert_status) and describing the two-step flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit step-by-step usage instructions (Step 1 this tool, Step 2 polling tool) and details the polling process. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses behavioral traits like automatic owner following and caching for 5 minutes, which goes beyond a basic read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear hierarchy: main description, workflow tips, and common use cases. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description explains what is returned (list of users, user details, follower ID). It covers prerequisites and provides enough context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already fully describes the single parameter. The description adds no additional parameter semantics, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all followers of a deal' and specifies it returns a list of users. It distinguishes itself from sibling tools like deals_add_follower and deals_remove_follower.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips (shows user details, includes follower ID for removal, deal owner auto-follow, 5-minute cache) and common use cases (view followers, before removing). Offers explicit guidance on when to use and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals the destructive nature (removes a participant) and an important limitation (cannot remove primary person). Could include more about side effects or authorization, but overall good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections: purpose, workflow tips, common use cases. It is concise without unnecessary words, though could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sibling tools and lack of output schema, the description adequately covers the operation, parameters, constraints, and a recommended workflow. It doesn't detail error states but is sufficient for a straightforward removal action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds extra context: distinguishes deal_participant_id from person_id and advises to get it via list_participants. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a participant from a deal' with a specific verb and resource. It distinguishes itself from sibling tools like deals_add_participant and deals_list_participants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips: use deals/list_participants first, clarifies that deal_participant_id is not person_id, and states the constraint of not removing the primary person. This helps the agent decide when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. It explains partial update behavior and custom field formats, but does not mention permissions, error handling, or side effects. It covers the main behavior but lacks full transparency on constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a summary, custom fields section, workflow tips, and common use cases. Front-loaded with purpose. Slightly long but each section is relevant and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters and no output schema, the description is thorough: covers update behavior, custom fields complexity, workflow tips, and common use cases. It references sibling tools for specific actions, making it complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. However, the description adds significant value: explains custom fields keys (display names vs hash), enum/set fields handling, and provides examples for common parameters like status, value, and stage_id, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing deal' and 'Updates one or more fields', using a specific verb and resource. It distinguishes from sibling tools like deals_create, deals_move_to_stage, and deals_mark_as_won by suggesting alternatives for stage changes and status updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('only provide fields you want to change') and when not to (use deals/move_to_stage for simple stage changes, update status field for won/lost). Workflow tips and common use cases provide concrete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses caching behavior ('Cached for 15 minutes') and lists the response fields, giving transparency about output. It does not mention rate limits or error handling, but for a read-only lookup, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief summary, response fields in bullet points, caching note, and common use cases. Every sentence serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, response structure, and caching behavior. Given no output schema and simple parameters, it provides sufficient context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, describing both parameters. The description adds value by showing a concrete example and explaining the context of parameters (entity types listed, field ID as identifier).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific field by ID and entity type.' This distinguishes it from sibling tools that list fields (e.g., fields_list_deal_fields) by focusing on a single field retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases and an example, implicitly indicating when to use this tool: when you have a specific field ID. However, it does not explicitly exclude alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions caching for 15 minutes and describes the return structure in detail. However, it doesn't explicitly state it's read-only or address any potential side effects, though the context implies it's a safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, return format, caching note, and use cases. It is detailed but concise, with every sentence adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return structure and caching behavior. It covers all necessary aspects for a retrieval tool, making it complete 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description doesn't need to add parameter information. The baseline of 4 is appropriate as no additional parameter context is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all field definitions across all entity types, serving as an aggregator. It distinguishes itself from sibling tools like fields_list_deal_fields by explicitly mentioning it combines multiple entity types in one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists common use cases such as getting a complete overview, building documentation, and auditing. While it doesn't explicitly say when not to use it, the aggregator nature implies it's for cross-entity needs, and specific entity tools exist for targeted queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses caching period (15 min), response structure (field id, key, type, validation, options), and purpose. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear sections. Front-loaded purpose, then details, then use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, description is complete. Explains response contents, caching, and common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so description adds meaning by detailing what the endpoint returns (field keys, types, validation, etc.) and use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get all field definitions for organizations' with specific resource (organization fields) and verb (list). Distinguishes from siblings like fields_list_activity_fields by specifying organization context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover what fields are available before creating or updating organizations.' Provides common use cases and caching info. Could mention alternatives but not required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses a 15-minute cache and details the output structure (field keys, types, validation rules, etc.). This gives agents good insight into behavior 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with bullet points and sections, covering purpose, use cases, output structure, and caching. It is concise (about 150 words) with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description provides a complete picture: what it does, when to use it, what the response contains, and caching behavior. It is sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters with 100% schema coverage. The description does not need to explain parameters further. According to guidelines, baseline is 4 for no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets all field definitions for products, including custom fields. The verb 'Get' and resource 'field definitions for products' are specific. It distinguishes from sibling field list tools by specifying 'products'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool to discover fields before creating or updating products, and lists common use cases. It provides clear context but does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses permanent deletion, removal from associated entities, irreversibility, and visibility in lists with include_deleted_files=true. Exceeds basic schema info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, with a clear main sentence, workflow tips, and common use cases. All content is relevant and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool with no output schema, the description covers behavior, side effects, and use cases completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'id' parameter. The description adds an example ('id: 123') but does not provide additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a file from Pipedrive' and explains permanence and removal of associations, distinguishing it from sibling tools like files_get, files_list, files_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips such as verifying with files_get first and warns that deletion cannot be undone. Includes common use cases but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses pagination behavior (default limit 100, max 500), sorting options, and the include_deleted_files flag. It omits details like default sort order or response structure, but covers key behaviors sufficiently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a one-sentence summary followed by bullet points and examples. Every sentence adds utility; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description covers pagination, filtering, sorting, and common use cases adequately. It lacks information on error handling or default sorting order, but for a list tool, completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value by listing sortable fields (add_time, update_time, file_name, file_size) and providing concrete examples of parameter combinations (e.g., '{ "deal_id": 123 }'). This goes well beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List files with pagination and filtering options', specifying the verb and resource. The examples (e.g., 'List all files for a deal') distinguish it from entity-specific list tools like deals_list_files, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases, e.g., filtering by entity and using pagination. However, it does not explicitly exclude alternatives like deals_list_files when listing files for a specific entity, so guidance on when to use this vs. sibling tools is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that results are heavily cached for 15 minutes, which is a behavioral trait. It also indicates it's a read-only operation returning data. No destructive effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first line, a brief statement, then 'Workflow tips' and 'Common use cases' sections with JSON examples. It is front-loaded and every sentence adds value without unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers purpose, parameter usage, caching, and example use cases. It is complete enough for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline 3. The description adds value by explaining the enum values for the 'type' parameter with examples and clarifies behavior when the parameter is omitted. This goes beyond the schema's 'description'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all filters in Pipedrive' with a specific verb and resource. It distinguishes from sibling tools like filters_get (single) and filters_bulk_delete by focusing on the listing action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases explain when to use the type parameter and that without it all filters are returned. Caching behavior is noted. However, no explicit exclusions or alternatives are mentioned, but the context is clear for a list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the status check behavior, possible statuses (queued, running, completed, failed), and that completion returns deal_id. This is adequate for a simple read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste. The first sentence states the core purpose, and the second provides specific instructions and outcomes. It is front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status check with two parameters and no output schema, the description covers all necessary aspects: purpose, prerequisite (conversion_id source), possible statuses, and expected output on completion. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that conversion_id comes from leads_convert_to_deal, which provides meaningful context beyond the schema. The id parameter description in schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check the status' and the resource 'lead-to-deal conversion job'. It implicitly differentiates from sibling tools like 'leads_convert_to_deal' and 'deals_convert_status' by specifying the context and referencing the conversion_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use the conversion_id from leads_convert_to_deal, providing clear when-to-use guidance. It lacks explicit when-not-to-use or alternative tools, but the context is sufficient for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: returns array of label objects, no pagination, heavy caching (24 hours). It does not mention authentication, but as a read-only operation, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, workflow tips, common use cases, and response format. Every sentence adds value, and it is appropriately sized without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and no parameters, the description fully covers the tool's behavior, use cases, and response format. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description does not need to add parameter details. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all lead labels (tags/categories)' and explains the resource and its purpose. It distinguishes itself from sibling tools like leads_list by focusing specifically on labels, not leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips (no pagination, caching, use of UUIDs) and lists common use cases. While it doesn't explicitly say when not to use, the context is clear and there are no alternative tools for labels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains archived leads are moved out of active inbox but not deleted or converted, and lists sorting and pagination behavior. Lacks mention of permissions or side effects, but for a read-only list, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a summary, workflow tips, and common use cases. Front-loaded with the main action. A bit verbose but each section provides useful guidance; could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description explains what the tool returns (paginated list of archived leads), how to paginate and filter, and provides examples. Covers essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 7 parameters with descriptions. The description adds value by explaining filter_id precedence over others, default and max limit, and sorting order, which enhances agent understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List archived leads with pagination and filtering options.' It distinguishes from sibling tools like leads_list (active) and leads_search by specifically targeting archived leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips including sorting order, filter precedence, pagination defaults, and common use cases with example parameters. It also mentions restoration via leads/update, guiding when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: permanent removal, irrevocability, and association scope. It clearly states 'cannot be undone' and 'cannot be recovered', leaving no ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with a clear hierarchy: summary, workflow tips, and common use cases. Every sentence adds value without redundancy, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one parameter, no output schema, no annotations), the description covers purpose, behavior, prerequisites, and examples comprehensively. An agent has all necessary information to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single 'id' parameter. The description adds an example usage '{ "id": 123 }' but does not provide additional semantics beyond what the schema offers, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a note from Pipedrive' with a specific verb and resource. It also differentiates from sibling tools like notes_create and notes_delete_comment by focusing on note deletion and emphasizing permanence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips warn about irreversibility and recommend verification with notes_get first. Common use cases are provided. However, it does not explicitly state when not to use the tool or name alternatives, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses behavior: returns a paginated list, supports pagination (start, limit, default 100, max 500), sorting, filtering by entity/user/pinned flags. Does not mention auth or rate limits, but these are likely system-level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with a clear header, summary, and bullet-pointed tips and examples. Every sentence adds value, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 optional parameters and no output schema, the description covers pagination, filtering, sorting, and common use cases comprehensively. It is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description enriches understanding by providing common use cases and examples showing parameter combinations (e.g., deal_id with pinned_to_deal_flag), default limit, and max limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List notes with pagination and filtering options,' specifying the verb 'List' and resource 'notes'. It distinguishes from sibling tools like notes_create, notes_get, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips and common use cases with JSON examples. It explains when to use filters and pagination, but does not explicitly mention alternative tools for specific scenarios (e.g., notes_get for a single note).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns a chronological list, shows fields changed, old/new values, who made the change, and when. It also mentions cursor-based pagination. It does not discuss rate limits or authentication, but for a read-only tool these are less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, bullet points for use cases, and a separate paragraph for changelog content. It is concise—every sentence adds value—and front-loads the core purpose. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description fully covers what the tool returns (changelog details), pagination behavior, and use cases. The 100% schema coverage compensates for missing output schema details. The description provides sufficient context for an agent to understand when and how to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining cursor-based pagination, which goes beyond the schema's basic parameter descriptions. For instance, it clarifies how to navigate through large change histories, but does not detail parameter formatting or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List updates about organization field values (changelog)'. It specifies the resource (organization fields) and action (list updates), distinguishing it from sibling tools like 'deals_list_field_updates' or 'organizations_list_updates' which cover different entities or broader updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: auditing, tracking modifications, understanding history, compliance. It does not explicitly exclude alternatives or state when not to use it, but the specificity of field-level changes implies appropriate context. With similar tools available, mentioning alternatives would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Clearly describes a read operation (returns list) with pagination, summary, and currency conversion behaviors. Does not mention permissions or rate limits, but the behavior is well-documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear main sentence followed by workflow tips and use cases. Slightly lengthy but all content adds value. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage for a 9-parameter tool with no output schema. Includes examples for all common parameter combinations and explains dependencies. No gaps in parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds significant value by explaining parameter interactions (e.g., everyone overwrites filter_id/user_id) and providing concrete examples for each parameter combination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get all deals in a specific pipeline' with specific verb and resource. Distinguishes from sibling tools like deals_list and pipelines_get by specifying pipeline context and providing distinct use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides workflow tips and common use cases with example parameter combinations. Offers guidance on filtering, pagination, and summary usage. Could be more explicit about when not to use this tool versus alternatives like deals_search, but the examples cover many scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses the returned information and implies a read-only operation, but does not explicitly mention permissions, side effects, or rate limits. However, for a simple GET tool, this is largely sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main description, workflow tips, common use cases, and example. Every sentence adds value, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary details: what it does, what it returns, how to use it, and an example. No gaps given the tool's simplicity and absence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id', already fully described in input schema. Description adds no additional semantic meaning beyond what schema provides. Baseline 3 due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool gets details of a single project template by ID, specifies the returned content (structure, phases, groups, tasks, and activities), and distinguishes from sibling tools like project_templates_list by explaining its specific use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips and common use cases, tells when to use (inspect before creating a project) and mentions alternative (projects/create) for creating from template.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of disclosure. It explains the behavior: makes a test request to GET /users/me, returns specific fields, and is cached for 60 seconds. It does not mention side effects (none expected), rate limits, or permission requirements, but for a health check, the transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main sentence, a bulleted list of returns, caching info, and common use cases. Every sentence is purposeful, and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a straightforward purpose, the description is complete. It covers the action, the API call, the return values, caching behavior, and typical use cases. No gaps are evident given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100%. The description does not need to add parameter meaning, but it does add value by describing the return fields. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks API connectivity and authentication. It uses a specific verb ('check') and resource ('API connectivity and authentication status'), and distinguishes itself from sibling tools by being a diagnostic tool, unlike the many data manipulation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Common use cases are listed (verify token, check API accessibility, get connection status before operations, troubleshoot). This provides context for when to use the tool, but it does not explicitly state when not to use it or mention alternatives. The guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that results are cached for 10 minutes and includes app-specific permissions. With no annotations provided, this covers important behavioral traits, though it could mention error handling or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with bullet points for workflow tips and common use cases, and front-loads the main purpose. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter and no output schema, but the description adequately explains what is returned (all permissions, access levels, restrictions) and includes caching behavior. This is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with a description for the required 'id' parameter. The description adds value by providing usage examples like { 'id': 123 }, aiding understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get user permissions' and explains it returns all permissions assigned to a user including access levels and restrictions. This is a specific verb-resource pair that distinguishes it from sibling tools like permission_sets_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Workflow tips and common use cases provide context for when to use the tool (auditing, verifying permissions). However, it does not explicitly exclude scenarios or compare to alternatives, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that data is fetched fresh (no caching) and details all returned fields. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, front-loaded with the main purpose. It is appropriately detailed without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides extensive information about return fields, use cases, and event combinations, making it complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description adds value by explaining the output fields and event combinations, exceeding the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all webhooks configured for the company.' It specifies the resource and action, and distinguishes from siblings like webhooks_create and webhooks_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (list active webhooks, audit endpoints, debug issues, manage webhooks) and explains event combinations, but does not explicitly exclude when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses permanent deletion, attached audio deletion, non-deletion of activity, and irreversibility. However, it does not mention authentication requirements or rate limits, which are minor omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections (main description, workflow tips, common use cases) and is front-loaded. It is efficient but could be slightly shorter without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description is complete. It explains effects, prerequisites, irreversibility, and provides examples, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter 'id' with description 'ID of the call log to delete'; coverage is 100%. The description adds context by advising to use call_logs/list to find the ID first and shows example values, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Delete a call log' and explains it permanently removes a call log. It distinguishes from siblings like call_logs_create, call_logs_get, call_logs_list, and call_logs_attach_audio by highlighting that the related activity is NOT removed, which is a key differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips: use call_logs/list to find the call log ID first, notes that audio is also deleted, activity remains, and the action cannot be undone. It also gives common use cases with example JSON, guiding exactly when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explains pagination behavior (default/max limit), client-side filtering caveat for date fields, and mentions alternative for complete results. Does not explicitly state read-only nature but is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with clear sections (workflow tips, common use cases). No redundant sentences; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive given 14 parameters and no output schema. Covers pagination, filtering, alternatives, and limitations. Missing explicit mention of return format but not required without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 14 parameters are described in schema (100% coverage). Description adds value by explaining enum meanings, providing usage patterns (e.g., owned_by_you=1), and examples for common scenarios.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists deals with pagination and filtering. It distinguishes itself from sibling tools like deals_list_all_auto and deals_search, and includes common use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use this tool versus alternatives (deals_list_all_auto for full pagination-free results). Warns about client-side filter limitations for date ranges and suggests alternative. Provides workflow tips and common examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses that moving stages may trigger automations in Pipedrive, which is a key behavioral trait. It does not detail authorization requirements or reversibility, but the automations warning adds meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear front-loaded purpose statement, followed by bullet-pointed workflow tips and use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers purpose, usage, prerequisites, side effects, and examples. It lacks explicit return value description, but given the tool's simplicity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value through workflow tips (e.g., stage must be in same pipeline) and example use cases showing typical stage_id values (5 and 10). This aids understanding beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool moves a deal to a different stage in the pipeline and distinguishes it from deals_update by advising 'Use this instead of deals/update when only changing stages.' The verb 'Move' and resource 'deal stage' are specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('only changing stages') and when-not-to (use deals/update for other changes). It includes workflow tips: using pipelines/list to get stages, warning about automations, and stage must be in same pipeline or specify pipeline_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explicitly states 'Read-only', mentions caching (15 minutes), and clarifies that fields cannot be created/updated/deleted via API. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences plus bulleted use cases), front-loaded with the main action, and every sentence adds value (purpose, read-only, cache, use cases). No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool’s simplicity (no params, no output schema), the description covers purpose, safety, caching, and use cases. It lacks detail on the response structure, but the agent can infer from 'field definitions' and use cases. Adequate for a metadata endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and schema coverage is 100%. Per guidelines, baseline is 4 for zero parameters. Description adds no parameter info because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all field definitions available for notes' with a specific verb and resource. It clearly distinguishes from siblings like fields_get_field and fields_list_all_fields by scoping to notes only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases (discover structure, find field keys) and notes the cache duration. It does not explicitly compare to alternatives but the purpose is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explicitly states no content modification, character limits, and that at least one field is required. Fully transparent about tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with short summary, workflow tips, and examples. Every sentence adds value. Front-loaded with core action and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does and constraints. Lacks mention of return value (e.g., updated file object or success status), but given simplicity, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so baseline is 3. Description adds value with examples, character limits, and reminder that name should be without extension. Exceeds minimal requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates file metadata (name or description) and explicitly notes it does not modify content. It distinguishes itself from sibling tools like files_upload or files_delete by specifying its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use (rename, update description) with workflow tips and common use cases. Does not explicitly state when not to use, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses automatic pagination, large dataset warning, sorting by creation time, and client-side date filtering. It does not discuss rate limits or auth, but covers key behavioral traits adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a brief intro, warning, workflow tips, and common use cases. Every sentence adds value; no redundancy. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains what to expect (list of leads, large dataset, sorted by creation time). Covers essential aspects for a list-all tool; could mention response format but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining that filters are same as leads/list and that max_items limits total results. It clarifies that no start/limit management is needed, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches ALL leads with automatic pagination, specifying it returns non-archived leads matching filters. It distinguishes from leads/list by emphasizing that this returns all results in a single response.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool versus alternatives (leads/list for paginated results, this for comprehensive analysis). Provides workflow tips and common use cases, giving clear guidance on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses consequences: irreversible deletion, loss of organizations, custom fields, notes, follow relationships, and potential retention of activity history. Also mentions rate limits for large deletions, providing essential 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, use cases, warning, best practices, parameter details). It is concise yet comprehensive, with no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers tool purpose, impact, best practices, and parameter format. While it mentions rate limits vaguely and lacks error handling details, it is sufficiently complete for a single-parameter bulk delete tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 100% schema coverage, baseline is 3. The description adds value by clarifying that 'ids' is a comma-separated string and providing an explicit example, which goes beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'multiple organizations in bulk', distinguishing it from individual delete tools like organizations_delete and from other bulk delete tools (e.g., deals_bulk_delete). It provides a specific purpose with example use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists scenarios for use (data cleanup, GDPR compliance, etc.) and includes best practices (verify IDs, export backup). However, it does not explicitly specify when to avoid using this tool or mention alternative tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden of behavioral disclosure. It explains cursor-based pagination, date filtering, and performance benefits for large datasets. However, it does not explicitly state that the tool is read-only or non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points, but some statements are redundant (e.g., 'Better performance' and 'Better for ETL' convey similar ideas). Overall efficient, with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers usage, parameters, and key differences from alternatives. However, it lacks details about the response format, such as how to interpret the cursor for further pagination. Given no output schema, this additional context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value by detailing each parameter's purpose, default values, constraints (e.g., max 500), and formatting (YYYY-MM-DD). It also explains how parameters like 'since' enable incremental sync.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves organizations via a collection endpoint with cursor-based pagination and date filtering. It explicitly differentiates from organizations/list, highlighting unique capabilities like cursor pagination and date-range filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (initial sync, incremental updates, large-scale exports) and contrasts with the sibling tool organizations/list. It explains when cursor pagination is beneficial over offset pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the effects of removal in detail: no more notifications, but access remains if permissions allow. It clarifies that only notification settings are affected, not access rights. No annotations provided, so the description fully carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear one-line summary at the start, followed by detailed bullet points of effects and use cases. Every sentence adds value, and the note about follower_id is appropriately placed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, effects, and use cases. However, it does not explicitly mention whether the deletion is reversible (i.e., if a follower can be re-added later). Given the lack of 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by clarifying that follower_id is the user ID of the follower to remove, which is not explicitly stated in the schema description (only 'User ID of the follower to remove'). This adds useful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a follower from a person,' which is a specific verb-resource pair. It distinguishes the tool from siblings like persons_add_follower and persons_list_followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists specific use cases: managing notification preferences, adjusting team involvement, reducing notification noise, changing account ownership responsibilities. It does not explicitly state when not to use it, but the context implies it's for removing followers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses critical behaviors: permanent deletion, removal of all stages, and the need to move deals before deletion. It also advises verifying with 'pipelines_get first'. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, consequence list, workflow tips, and examples. It is slightly verbose but all sentences add value. Minor redundancy in listing consequences in both tips and examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter, the description covers all necessary context: purpose, side effects, prerequisites, alternatives, and verification step. No output schema exists, but the description adequately addresses what the tool does and its impacts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a simple 'id' parameter description. The tool description adds a usage example ('Remove pipeline: { "id": 1 }') but does not provide additional semantic 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a pipeline' and specifies that it permanently removes the pipeline and all its stages. It distinguishes from siblings like 'deals_delete' by explicitly naming the resource and providing context about pipeline-specific consequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit workflow tips: irreversible action, need to move deals first, suggestion to deactivate instead, and verification step. It tells when to use and when to consider alternatives ('Consider deactivating instead of deleting').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it requires admin permissions and mentions behavioral implications like hierarchy changes and name uniqueness. However, it does not explain error responses or behavior if the role does not exist. With no annotations, the description carries the burden and covers key traits well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a brief introductory sentence followed by bullet points for workflow tips and use cases. Every sentence adds value without redundancy, and examples are front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with three parameters and no output schema, the description adequately covers purpose, prerequisites, workflow, and examples. It does not explain return values, but that is acceptable given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond schema definitions by providing example JSON bodies and explaining the effect of changing parent_role_id. This helps the agent understand parameter usage beyond syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update role details' and 'Updates information for an existing role,' using a specific verb and resource. It distinguishes from sibling tools like roles_create, roles_delete, and roles_get by focusing on update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips: only provided fields are updated, use roles/get to retrieve current values, and notes on uniqueness and hierarchy. Common use cases with JSON examples give clear context on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It reveals auth requirements (admin permissions), effect scope (affects all users), and a constraint (value type match). However, it does not mention error behavior or response format. This is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a short summary, followed by bullet-pointed workflow tips, and a usage example. Every sentence adds value without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, effects, and usage tips. However, it lacks any mention of return values or error handling, which would be helpful since there is no output schema. For a simple update tool, this is mostly adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds a JSON example and a constraint on value type ('should match original setting'), which provides additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a role setting') and specifies the resource. It is distinct from siblings like roles_add_role_setting (add) and roles_delete_role_setting (delete). The purpose is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips: setting must already exist, use roles/get_role_settings to view current settings, changes affect all users with this role, and value type must match. It also notes the requirement for admin permissions. This gives clear when-to-use and prerequisite guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses search behavior (term length rules, pagination via start/limit, result_score for relevance) but does not explicitly state it's read-only (reasonable assumption). Could be improved by confirming no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and labeled sections, but slightly verbose with repeated 'Search' in examples. Could be trimmed without loss of clarity, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and 100% schema coverage, the description covers key usage scenarios and parameter behavior. Mentions result_score but could detail response structure more. Lacking output schema is acceptable as per rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema covers 100% of parameters, the description adds significant value by elaborating on usage (e.g., 'Term must be at least 2 characters (1 if exact_match)'), providing contextual examples, and explaining implications like related items limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search across all Pipedrive entities' and lists specific entity types. It distinguishes from entity-specific sibling tools like search_deals by emphasizing cross-entity search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips (minimum character length, item_types usage, exact_match, related items) and common use cases with JSON examples. Effectively guides when to use different parameter combinations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly explains that the tool is read-only, returns a list with detailed field descriptions, and is cached for 24 hours, which sets expectations about data freshness. No contradictions or omissions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for return fields and common use cases. It is somewhat lengthy but uses bullet points effectively. Every sentence adds value, though some repetition could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains all return fields in detail, mentions caching behavior, and provides common use cases. It is comprehensive for a zero-parameter read tool, especially given no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters (100% coverage), so baseline is 4. The description adds value by explaining the output fields and their semantic meaning, which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool returns a list of supported currencies and exchange rates, listing specific fields like currency codes, symbols, names, exchange rates, active flag, and decimal precision. It distinguishes itself from siblings by being a read-only system tool for currency data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases such as getting supported currencies before creating deals, validating currency codes, and understanding exchange rates. It mentions the caching behavior, which implies that for real-time updates, alternative tools might be needed, but doesn't explicitly state when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses caching behavior ('Cached for 5 minutes'), partial match support, and that it searches within the company. This adequately informs the agent of key behavioral traits without hidden surprises.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into sections ('Workflow tips', 'Common use cases'), uses bullet points for readability, and every sentence serves a purpose. It is concise yet comprehensive, avoiding unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description covers all necessary aspects: purpose, usage guidelines, parameter details, behavioral notes, and examples. An agent can confidently select and invoke this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema: it explains the difference between searching by name vs email, provides example inputs for both parameters, and clarifies that 'search_by_email' is a numeric flag. This fully compensates for any potential ambiguity in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find users by name or email' and elaborates on the search scope within the company. The verb 'find' and resource 'users' are specific, and the tool is well-distinguished from sibling tools like users_list and persons_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes workflow tips indicating when to use this tool ('faster than filtering users/list results') and provides common use cases with examples. However, it does not explicitly mention when not to use it or compare it to alternative tools like persons_search or search_universal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors: partial update ('Only provided fields'), uniqueness constraint on email, and restriction on admin status. However, it does not mention the return value (e.g., the updated user object) or error handling, and no output schema is provided. Annotations are absent, so the descriptions carries this burden well but not completely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a brief summary, followed by 'Workflow tips' and 'Common use cases'. Each sentence adds value, no redundancy. Front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description covers purpose, parameters, usage guidelines, and behavioral constraints. Missing is the return value/response format and potential errors, but overall it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value through workflow tips and examples showing how parameters are used (e.g., 'Update user name: {"id": 123, "name": "John Smith"}'). It clarifies the partial update behavior and the uniqueness constraint on email.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Updates information for an existing user') and the resource ('user'), with specific examples of fields like name, email, and active_flag. It distinguishes from sibling tools like 'users_create' and 'users_get' by focusing on existing users and partial updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Requires admin permissions', 'Only provided fields will be updated', 'Use users/get to retrieve current values first', 'Email must remain unique if changed', and 'Cannot update own admin status'. It also gives common use cases with example payloads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the action is permanent, immediately stops notifications, cannot be undone, and that webhooks can be recreated. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and front-loaded summary. Slightly long but each section adds value. Not overly verbose for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple delete tool with one parameter and no output schema. Covers purpose, use cases, workflow, notes, and best practices thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with schema description 'ID of the webhook to delete (required)'. Description adds no extra meaning beyond schema; baseline 3 due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook by its ID. Permanently removes a webhook from Pipedrive.' This provides a specific verb and resource, and among sibling tools (webhooks_create, webhooks_list), it is distinctively deletion-focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to delete (endpoint invalid, stop notifications, cleanup, etc.), provides a workflow referencing webhooks/list, and advises on verification. It also contrasts with creation and listing tools implicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses critical behavior: deletion is permanent and cannot be undone, and failed deletions for individual activities do not block others. This is transparent for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: brief purpose, bulleted workflow tips, list of use cases, and a JSON example. Every sentence adds value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, destructive bulk operation, the description covers constraints (max 100, permanence), permissions (must be accessible), error behavior (partial failures), and usage context. No output schema needed; the action outcome is implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the 'ids' parameter. The description adds an example but does not provide new semantic meaning beyond the schema. Per rules, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete multiple activities in a single request', specifying the verb (delete) and resource (multiple activities). It distinguishes from siblings like 'activities_delete' (single) and other bulk delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips: max 100 per request, all IDs must exist and be accessible, permanent deletion, and partial failure behavior. Lists common use cases, helping the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that removing a follower stops notifications, and explicitly states a limitation (cannot remove deal owner). It could mention whether the operation is reversible or any idempotency, but overall provides sufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise purpose sentence, effect, workflow tips, and a common use case example. Every sentence serves a purpose, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema and no annotations, the description covers all necessary aspects: purpose, effect, workflow, limitations, and a usage example. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value beyond the schema by clarifying the relationship between follower ID and user ID, and by providing a workflow example. This extra context helps the agent use the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a follower from a deal' and explains the effect 'Stops a user from receiving notifications about this deal.' It distinguishes from related tools like deals_add_follower and deals_remove_participant by focusing on followers specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips: using deals/list_followers to get follower IDs, noting that follower ID differs from user ID, and stating that the deal owner cannot be removed. This helps an agent understand when and how to use the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses important behavioral details: it is a soft-delete that preserves existing values on records but hides the field from UI and new payloads. This fully compensates for the lack of annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each providing essential information. The first sentence front-loads the primary purpose, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers purpose, behavior (soft-delete), and effect on records and UI. It is complete given the tool's simplicity and the available structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id', with a clear description in the schema. The tool description adds 'custom organization field' context but does not significantly enhance parameter meaning beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete a custom organization field by ID', specifying the resource (organization field) and the method (by ID). It distinguishes from the bulk deletion tool by explicitly mentioning the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool and provides an alternative for bulk deletions: 'Use `fields_bulk_delete_organization_fields` to delete several fields in one call.' This guides the agent on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses soft-delete behavior: 'Existing values are preserved on records but the field stops appearing in the UI and new payloads.' Since no annotations, description fully handles transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: action, soft-delete explanation, alternative tool reference. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides all needed context for a one-parameter tool: what it does, soft-delete outcome, and alternative for bulk. No gaps given schema coverage and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes the single parameter 'id' with full coverage. Description adds no extra parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a custom product field by ID.' Distinguishes from sibling tool `fields_bulk_delete_product_fields` by mentioning it for bulk operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs. the bulk alternative: 'Use `fields_bulk_delete_product_fields` to delete several fields in one call.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully carries the burden. It discloses caching behavior ('Cached for 15 minutes') and describes the response structure comprehensively. This is transparent for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and common use cases. It is concise, front-loaded with the main purpose, and every sentence earns its place without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No parameters or output schema exist, yet the description fully covers what the tool does, its response structure, caching, and usage scenarios. There are no gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the baseline is 4. The description adds value by detailing the response contents and their purpose, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all field definitions for activities, including custom fields.' This is a specific verb-resource pair that distinguishes itself from sibling tools like fields_list_deal_fields and fields_list_organization_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use case: 'Use this to discover what fields are available before creating or updating activities.' Common use cases are listed. However, it does not explicitly state when NOT to use it or mention alternatives, though the tool name and context make it obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: returns field definitions with structure, caching for 15 minutes, no side effects. Also mentions filtering/sorting capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear sections. Front-loads purpose. Slightly verbose but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a parameterless tool: details output structure, caching, and use cases without needing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters. Description correctly adds no parameter info beyond schema. Schema coverage is 100% and no param explanation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get all field definitions for deals' with specific verb and resource. It distinguishes from sibling tools like fields_list_activity_fields by specifying 'for deals' and including custom fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: discover fields before creating/updating deals, check types, find keys, understand enum options. Lacks explicit when-not-to-use but context implies usage before mutations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully handles behavioral transparency. It states deletion is permanent and cannot be undone, and that the filter will no longer be available. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for description, workflow tips, and common use cases. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description covers effect, prerequisites, and provides examples. It is fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (id) with 100% schema coverage. Description adds examples of common use cases (e.g., delete filter with id 123), but these are not essential 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool deletes a filter in Pipedrive. The description specifies the resource (filter) and action (delete), and distinguishes from filters/bulk_delete for deletion of multiple filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips: use filters/list to find IDs, filters/get to verify, and notes filters/bulk_delete for multiple deletions. Also includes common use cases, which guide the agent on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that results are heavily cached for 15 minutes, which is a key behavioral trait. It also notes no parameters are needed. However, it does not mention permissions or rate limits, which are minor omissions for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear bullet points and workflow tips. Every sentence adds value, and the main purpose is front-loaded. It is concise for the amount of information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature (zero parameters, no output schema, read-only), the description fully covers what the tool does, when to use it, and its caching behavior. It is complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is 100%. The description does not need to add parameter semantics, and per rubric, baseline for 0 params is 4. It appropriately states no parameters are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all available filter helpers and field types, listing specific information like field IDs, operators, data types, and options. It distinguishes from sibling filter tools (e.g., filters_create) by focusing on discovery rather than manipulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Workflow tips' advising to use this tool BEFORE creating or updating filters, and common use cases that help an agent decide when to invoke it. This provides clear guidance on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the async nature, return statuses, polling requirement, and transfer of related entities, providing complete behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with numbered steps, and contains no unnecessary information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description adequately explains the tool's output, the required follow-up action, and the behavior regarding related entities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already described in the schema as 'Lead UUID to convert'. The description only reiterates this, adding minimal extra meaning. Schema coverage is 100%, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool converts a lead into a deal as part of a two-step asynchronous flow, distinguishing it from sibling tools like leads_convert_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear step-by-step instructions: Step 1 initiates the conversion, Step 2 requires polling leads_convert_status with both IDs until completed. It explicitly tells when to use this tool versus the polling step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permanent deletion, irreversibility, and return value. No annotations provided, so description carries full burden; lacks auth/rate limit info but acceptable for simple delete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: clear sections (description, workflow tips, common use cases, alternative). No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter delete tool with no output schema, description covers behavior, usage, and alternatives completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already documents 'id' with description. Description reinforces UUID format and provides example, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a specific lead' with emphasis on permanence. Distinct from sibling leads_update which offers archiving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use (delete) vs when to archive (alternative via leads_update). Includes UUID requirement and irreversible nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details behavioral traits: sources are pre-defined and immutable, leads created via API get 'API' source assigned automatically, results are heavily cached (24 hours). No annotations are provided, but the description fully compensates by disclosing these critical behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, making it easy to scan. While slightly long, every sentence serves a purpose: listing sources, explaining caching, and offering use cases. It could be pared down slightly, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description covers all necessary context: what the tool returns (list of source names), immutability, default assignment, caching, and example use cases. It is fully sufficient for an agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description does not need to explain any. The description adds value by listing the actual source values (Manually created, Deal, etc.), which is more informative than the empty schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get all lead sources', and explains what lead sources are and where they come from. It distinguishes itself from siblings like leads_get (which gets a specific lead) and leads_get_labels (which gets labels) by focusing solely on the fixed list of source origins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (list all sources, reporting, display to users) and important workflow tips (sources are fixed, heavily cached, list may expand). It does not explicitly state when not to use it, but the context is clear and sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that admin permissions are required, that deletion is blocked for roles with active assignments, and that sub-roles may need reassignment. These behavioral traits are well documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief main sentence, permission note, bulleted workflow tips, and a common use case example. It is concise, front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 covers permissions, prerequisites, constraints, and provides an example, making it fully complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id' described as 'ID of the role to delete'. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a role' and 'Removes a role from the company', specifying the verb and resource. It distinctively identifies the action compared to sibling tools like roles_create or roles_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow tips: cannot delete role with active assignments, recommends checking assignments first via roles/get_role_assignments, and notes sub-roles may need reassignment. It also requires admin permissions, offering clear guidance on when and how to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It confirms the tool is read-only ('Get information'), discloses 60-second caching, and details the response structure, leaving no ambiguity about safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and bullet points, making it easy to parse. It could be slightly trimmed without losing information, but it remains effective and comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description provides a thorough list of response fields and common use cases. An agent has all necessary information to decide when to call this tool and interpret its results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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%, so there is no need for additional parameter documentation. The description adds no redundancy and correctly focuses on the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves information about the currently authenticated user, listing specific fields like ID, name, email, permissions, timezone, etc. It distinguishes itself from sibling tools like 'users_get' by focusing on the current user's context without requiring a user ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (checking permissions, retrieving timezone/currency) and notes caching behavior. While it doesn't explicitly say when not to use it or name alternatives, the context signals are clear enough for an agent to understand its role among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It explicitly mentions cursor-based pagination for large result sets, and all filtering behavior is clearly described. There is no contradictory information, and the description accurately reflects that the tool is a safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive. It is structured with a clear main sentence, a pagination note, a bullet list of workflow tips, and then a list of common use cases with inline JSON examples. Every part serves a purpose, and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are 6 optional parameters, no output schema, and no annotations, the description covers all necessary aspects: pagination (cursor/limit), all filter parameters with examples, and common query patterns. The agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds substantial value beyond the schema. It groups related parameters into workflows (e.g., pagination, filtering by assignee/project) and provides practical JSON examples showing common use cases, which helps an agent understand parameter combinations and usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get all tasks with optional filters,' which clearly states the verb (get) and resource (tasks) with the key differentiator (optional filters). It explicitly mentions cursor-based pagination and filtering by assignee, project, parent task, and completion status, distinguishing it from sibling tools like projects_tasks_list (which is project-specific) and tasks_get (single task).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow tips and common use cases with concrete JSON examples, such as listing incomplete tasks or filtering by user. It implicitly guides the agent on when to use this tool (e.g., for listing tasks with filters) but does not explicitly state when not to use it or mention alternatives like projects_tasks_list. Still, the examples are highly instructive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: soft delete (marks as inactive, active_flag = false), only custom types, system types unaffected. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized into sections: title, description, workflow tips, common use cases. Each sentence adds value. Two example use cases are concise and informative. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema and no annotations, the description is fully complete. It covers behavior, limitations, side effects, and prerequisites. Examples illustrate usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear 'id' description. The description adds value by recommending a prerequisite step (list to find ID) and showing example formats for the ID. Exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete an activity type' and explains it marks as deleted. It distinguishes from siblings like 'activities_delete' by focusing on activity types, not activities themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use: only custom activity types. Includes workflow tips like finding the ID via 'activity_types/list' and checking 'is_custom_flag'. Also explains consequences (existing activities retain type, not available for new).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses all critical behaviors: source deletion, transfer of activities/notes/followers, merging of products/files/participants, and irreversibility. No annotations were provided, so the description fully covers the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with clear sections (description, workflow tips, common use cases, warning). Every sentence adds value without redundancy. Front-loads key information about deletion and target preservation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Thoroughly covers all relevant aspects: purpose, parameter roles, data transfer details, irreversibility, and examples. No gaps remain given the tool's complexity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes each parameter well (100% coverage). The description adds context by clarifying the roles of source and target, providing examples, and explaining consequences beyond schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it merges two deals, specifying which deal is deleted and which is kept. It distinguishes itself from sibling tools like deals_delete or deals_update by focusing on merging and data combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use (e.g., duplicate cleanup), which ID is source vs target, and workflow tips like reviewing deals before merging. Includes common use cases and clear warnings about irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: read-only, cached for 15 minutes, returns canonical list for leads, and notes shared structure with deals. This provides essential context for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: main purpose stated first, then behavioral details, caching info, and use cases. Every sentence adds value; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers all necessary aspects: purpose, behavior, caching, usage context, and relationship with sibling tools. It is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description cannot add parameter-specific meaning. Schema coverage is 100% trivially, so baseline is 4. The description does not need to compensate for missing parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all field definitions available for leads, including custom fields.' It uses specific verb (Get) and resource (field definitions for leads), and distinguishes from sibling tools like fields_list_deal_fields by specifying it applies to leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly says it's read-only and directs users to deal field tools for create/update/delete. It also mentions caching (15 minutes) and lists common use cases, providing clear guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details all behavioral traits: data transfer for deals, activities, notes, files, persons, custom field merging, and permanent deletion of the secondary organization. It explicitly labels the action as irreversible. This is comprehensive and exceeds expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bullet points, and front-loaded purpose. Every sentence provides value—no filler. Length is appropriate for the complexity of a merge operation with irreversible consequences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all necessary aspects: purpose, parameters, side effects, best practices, use cases. It leaves no critical gap for an AI agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description reinforces parameter roles (id as primary, merge_with_id as secondary) and adds context like 'The organization with ID 'id' will be kept.' While schema already defines purpose, the description adds meaningful clarity about ordering and deletion, justifying above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action verb and resource: 'Merge two organizations into one.' It lists specific transferred data types, making the scope unambiguous. Among sibling tools like organizations_create, organizations_delete, and organizations_update, this stands out as a distinct merge operation. Context signals confirm sibling differentiation is well-handled.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit best practices and use cases, such as 'Review both organizations thoroughly' and 'Use organizations/get to verify first.' It warns when not to use (e.g., merging different organizations) and suggests verification steps. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: the operation is irreversible, marks stages as deleted, returns an array of deleted IDs, and warns about impact on deals. This provides sufficient transparency for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (workflow tips, common use cases) and is front-loaded with purpose. However, it is somewhat verbose, containing multiple redundant statements (e.g., 'mark as deleted' repeated). A slightly more concise version could improve score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple delete operation with one parameter and no output schema, the description covers all necessary context: deprecation, irreversibility, return value, and common use cases. It provides a complete picture for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant meaning beyond the schema by specifying the format (comma-separated), providing an example ('1,2,3'), and explaining what happens to the IDs. This extra context justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes multiple stages in bulk, distinguishing it from the singular stages_delete. It provides specific verb ('delete') and resource ('multiple stages'), and the deprecation note further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the endpoint is deprecated and recommends using stages_delete instead, which is a clear when-not-to-use guidance. It also provides workflow tips including comma-separated IDs, irreversibility, and impact on deals, offering comprehensive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavioral traits: immediate test request, endpoint accessibility requirement, automatic disabling on repeated failures, and security considerations. No contradictions with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is lengthy but well-structured with clear sections (Required fields, Webhook triggers, Security, Version, Workflow tips, Example payloads, Important notes). Every section adds necessary information; front-loaded with purpose. Slightly verbose but justified by complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (3 required) and no output schema, the description covers all aspects: purpose, usage, parameter details with examples, behavioral notes, and workflow. No gaps remain for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3, but the description adds significant value beyond schema: provides common combinations, clarifies auth fields must be together, explains version defaults, and includes example payloads for all major use cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new webhook to receive real-time notifications', clearly identifying the verb and resource. It distinguishes from sibling tools webhooks_delete and webhooks_list by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance with required fields, event combinations, security tips, and workflow steps. Implicitly differentiates from listing and deleting by focusing only on creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosure includes permanent and irreversible deletion, and notes that related activities and notes are preserved but detached. Despite no annotations, the description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: main action, warning, workflow tips, and common use cases. Every sentence earns its place, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-id tool, the description covers all aspects: what it does, its permanence, alternative approaches, and example use cases. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes the id parameter (100% coverage), but the description adds context with usage tips and concrete examples (e.g., 'Delete test deal: { "id": 123 }'), enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a deal permanently' and warns against accidental deletion, distinguishing it from alternatives like marking as lost. It differentiates from siblings such as deals_update and deals_mark_as_lost.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises considering marking as lost instead, and provides workflow tips like verifying the deal with deals/get first. It tells when to use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: returns non-archived leads only, sorted oldest to newest, pagination defaults, filter precedence, client-side date filtering (only current page), custom fields inheritance. Comprehensive for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections 'Workflow tips' and 'Common use cases.' Every sentence adds value. No redundancy or wasted words. Concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return: a paginated list of non-archived leads. Covers all parameters, sorting, pagination, and caveats. Complete for a complex list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds significant context: filter_id takes precedence, add_time_from/until are client-side and page-limited, default limit 100 max 500, custom fields inherited from deals. Adds meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List leads with pagination and filtering options.' It specifies it returns non-archived leads, sorted by creation time, and provides common use cases. Distinguishes from siblings like leads_list_all_auto and leads_list_archived.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow tips: when to use filters, pagination limits, filter_id precedence, client-side date filtering limitations, and alternative tool leads_list_all_auto for full date-range results. Covers when-not-to-use as well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses irreversible deletion, data transfer details, and warnings. Covers what happens to the secondary person and all related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points, sections for warnings, best practices, and use cases. Front-loaded with main purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly covers input, process, side effects, and context. Provides all necessary information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the input schema by explaining primary (id) vs secondary (merge_with_id) roles, and that the secondary will be deleted. Schema coverage is 100% but description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Merge two persons into one' and lists specific actions (transfer deals, activities, etc.), distinguishing it from sibling tools like persons_delete or persons_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit best practices (review both persons, ensure duplicates) and use cases (removing duplicates, data cleanup). Gives guidance on when to use and alternative tool persons_get for verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-pipedrive MCP server](https://glama.ai/mcp/servers/nubiia-dev/mcp-pipedrive/badges/card.svg)](https://glama.ai/mcp/servers/nubiia-dev/mcp-pipedrive)

Score Badge

Copy to your README.md:

[![mcp-pipedrive MCP server](https://glama.ai/mcp/servers/nubiia-dev/mcp-pipedrive/badges/score.svg)](https://glama.ai/mcp/servers/nubiia-dev/mcp-pipedrive)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nubiia-dev/mcp-pipedrive'

If you have feedback or need assistance with the MCP directory API, please join our Discord server