Mob (Demo)

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about the journal mode including participant names, which is beyond the schema. However, it does not disclose other behavioral traits such as pagination behavior, default sorting, or that include_deleted is honored, leaving room for ambiguity.

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

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

The description is two concise sentences, front-loaded with the primary action 'List activities', and every word adds value. No unnecessary repetition of schema details.

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

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

Given the tool has 8 parameters but no output schema or annotations, the description covers the main use cases (filtering, journal mode) without needing to explain every parameter. The schema handles the remaining details. It stops short of a 5 because it omits mention of pagination or sorting behavior, which could be relevant to an agent.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning by grouping parameters into 'filtered by contact or type' and clarifying that days_back/since trigger a journal mode with participant names, which is not explicitly in the schema. This enhances understanding of how the parameters are intended to be used.

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

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

The description clearly states the tool lists activities and specifies optional filters by contact or type, as well as a chronological journal mode with participant names. It distinguishes the core function but does not explicitly compare against related sibling tools like contact_timeline or activity_manage, so it falls short of a 5.

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

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

The description implies when to use the tool (for listing activities, optionally filtered, or with days_back/since for a journal) but does not provide explicit guidance on when to choose an alternative tool or when not to use this one. No exclusions or alternatives are mentioned.

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

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

No annotations exist, so the description carries the behavioral burden. It discloses soft-delete behavior and the existence of restore, which is valuable, but it omits response/return behavior, error conditions, permissions, or side effects beyond the operation itself.

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

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

The description is a compact bulleted list, front-loaded with the full action list, and every sentence contributes practical information. No filler or redundancy.

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

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

For a 10-parameter, 5-action dispatch tool with no output schema, the description covers all action branches, required vs. optional fields, and soft-delete semantics. It lacks return-value expectations for create/update/delete/restore and explicit sibling exclusions, 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.

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 mostly restates what the schema already declares (e.g., 'id is required for get/update/delete/restore'), though it aggregates this information into per-action rules. It adds little new semantic meaning beyond the schema.

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

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

The description opens with 'Create, get, update, delete, or restore an activity/interaction,' giving a specific verb+resource. The bulleted actions clearly distinguish this from siblings like activity_list (which lists) and batch_create_activities (which batches creates).

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

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

Each action is paired with explicit required and optional parameters, so the agent knows which action and fields to use for a given scenario. However, it does not explicitly compare against alternatives or say 'when not to use this tool' (e.g., for bulk creation use batch_create_activities).

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

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

Without annotations, the description must carry the burden of behavioral disclosure. It states the core actions (list, create, update, delete), which implies mutation for the latter three. However, it omits details such as side effects, permissions, soft vs. hard deletes, or return values, offering only minimal transparency for a CRUD tool.

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

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

The description is a single, concise sentence that fully captures the tool's purpose with no extraneous words. Every word earns its place.

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

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

The tool has five parameters and no output schema, and the description is minimal. The schema covers parameter requirements, but the description does not clarify return values or operational nuances for each action, leaving some context incomplete for a multi-action CRUD tool.

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

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

The input schema provides descriptions for all five parameters, achieving 100% coverage. The description adds no additional parameter meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List, create, update, or delete custom activity types.' It uses specific verbs and identifies the resource (custom activity types), distinguishing it from sibling tools like activity_manage which likely manage activities themselves.

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

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

The description implies usage for managing custom activity types but provides no explicit guidance on when to use this tool versus alternatives, nor does it describe any exclusions. The action enum gives some context, but there is no mention of when to choose this tool over other management tools.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose side effects such as primary address handling, whether removal cascades, or whether specific fields are required for each action. It only lists the three actions without behavioral context.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's three functions. It is minimal and free of unnecessary detail.

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

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

This is an 11-parameter tool with three distinct actions and no output schema or annotations. The one-sentence description does not explain action-specific requirements, such as which parameters apply to which action, nor does it describe the outcome or side effects. The schema fills in parameter details, but the description lacks operational context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already specifies; it merely names the actions at a high level.

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

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

The description uses specific verbs 'Add, update, or remove' and identifies the resource 'address for a contact', clearly distinguishing it from sibling tools like contact_method_manage. It is unambiguous and specific.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or conditions for each action. It merely states what the tool does, providing only implied usage based on the user's need.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It prominently discloses atomicity and rollback semantics, a critical behavior for a batch operation. It also states the batch size limit. Although it does not cover response format or permissions, the most important behavioral trait is covered.

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

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

The description is two sentences, front-loaded with the core action and followed by essential constraints. Every clause adds value: batch creation, size limit, and atomicity. There is no filler or redundant phrasing.

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

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

The description covers the key contextual aspects of a batch create tool: batch size and atomicity. Since there is no output schema, the lack of return value documentation is acceptable. The description is sufficient for an agent to understand the tool's scope and major behaviors, though it could mention validation or error handling.

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

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

Schema description coverage is 100%, with all parameters already explained in the schema. The description only repeats the max 50 items constraint, which is also present in the schema. Thus the description adds no significant parameter-level meaning beyond what the schema already provides.

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

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

The description clearly states the primary action ('Create') and resource ('multiple activities/interactions') with the batch context ('in one call'). It distinguishes from sibling tools like activity_list or activity_manage by emphasizing batch creation, and the name itself is informative.

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

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

The description implicitly guides usage: use this when creating multiple activities at once. It provides concrete boundaries (max 50 items, atomic rollback) that help decide if this tool fits. However, it does not explicitly name alternative tools or state when not to use it, so it misses the 'when-not' aspect.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation runs atomically and rolls back on any failure—a critical behavioral trait. It also reiterates the batch size limit. While it doesn't discuss response format or validation, the atomicity disclosure goes beyond 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.

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

The description is two sentences, immediately front-loaded with the core purpose. Every word earns its place, stating the function, the limit, and the atomic behavior without fluff.

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

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

The tool has a single parameter (contacts array) with rich schema descriptions, but no output schema. The description covers the batch limit and atomicity, which are the most critical contextual aspects. It doesn't mention what the response contains, but given the simplicity and atomic behavior, the description is reasonably complete.

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

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

Schema description coverage is 100%, with every property well-documented. The description adds no new parameter details beyond the schema, and the 'max 50' limit is already present in the array parameter description. Thus, the description does not enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states 'Create multiple contacts in one call', specifying the verb (create), resource (contacts), and scope (multiple/batch). This distinguishes it from the sibling contact_create tool by emphasizing the batch nature.

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

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

The description clearly implies use for creating multiple contacts at once and sets a maximum batch size of 50. It doesn't explicitly contrast with single contact creation or name alternatives, but the context is clear enough for an agent to infer when 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.

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

With no annotations, the description carries the full burden. It reveals two key behavioral traits: the tag is created if it doesn't exist, and the operation is atomic with rollback on any item failure. This goes beyond basic expectations and helps the agent understand side effects and failure semantics. It does not mention permission requirements or return format, but the provided details are substantial.

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

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

The description is three concise sentences, each adding critical information: the action, the limit, and the atomic behavior. No wasted words or repetition of name or title. It is front-loaded with the primary purpose.

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

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

For a batch operation with two parameters and no output schema, the description covers essential operational details (batch limit, tag creation, atomic rollback). It lacks explicit return value info, but given the simplicity and atomicity guarantee, the description is sufficiently complete. The presence of sibling tools for other operations further clarifies context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining that 'tag_name' can create the tag if it doesn't exist, and it reinforces the 50-item limit for 'contact_ids'. This goes beyond the schema's bare descriptions, providing meaningful context for correct invocation.

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

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

The description starts with a clear verb and resource: 'Apply a tag to multiple contacts in one call.' It distinguishes itself from siblings like contact_create (creates contacts) and tag_manage (manages tags) by specifying the batch tagging action. The scope is explicit and unambiguous.

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

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

The description provides clear context for when to use the tool: when you need to tag multiple contacts in a single operation. It states a batch limit (max 50) and mentions the atomic behavior, which informs usage. It does not explicitly name alternative tools or exclusions, but the context implies batching for efficiency.

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

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

No annotations are provided, so the description carries the full burden. It only says 'Create a new contact with basic info,' which does not disclose any behavioral traits such as required first_name, side effects, permissions, or response format. It essentially restates the tool's name without adding 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.

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

The description is a single sentence that front-loads the action with no wasted words. However, the phrase 'with basic info' adds little value and is somewhat misleading given the schema's breadth, preventing a perfect score.

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

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

With 23 parameters and no output schema, the description is too sparse to provide adequate context. It does not explain what the tool returns, when to use it relative to sibling tools, or any constraints beyond the schema. The description is minimally complete but insufficient for the tool's complexity.

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

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

The input schema has 100% description coverage for all 23 parameters, so the baseline is 3. The description adds no parameter-specific meaning beyond the vague 'basic info,' which does not help with parameter selection or syntax.

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

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

The description clearly states the action 'Create a new contact' with a specific resource, distinguishing it from siblings like contact_update and contact_delete. However, the phrase 'with basic info' is vague and does not clarify which of the 23 fields are considered basic, so it is 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.

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

The description provides no guidance on when to use this tool versus alternatives such as batch_create_contacts or contact_update. There is no mention of single-contact creation context, prerequisites, or exclusions, so the agent gets no decision support beyond the name.

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

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

With no annotations provided, the description discloses the key behavior of being a soft-delete (non-permanent) and reversible, which is critical for a delete operation. It does not cover permissions, error conditions, or effects on related data, but the core behavioral trait is stated.

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

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

The entire description is a single concise sentence with an informative parenthetical. It is front-loaded and contains no filler words.

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

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

For a simple one-parameter soft-delete tool, the description sufficiently covers the action and its reversibility. It lacks details on response behavior or edge cases, but the context of sibling tools and schema completeness make it adequate.

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

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

The input schema already documents contact_id as 'The contact ID to delete' with 100% coverage, so the description adds no additional parameter semantics. The baseline of 3 applies.

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

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

The description uses the specific verb 'soft-delete' with the resource 'contact', clearly distinguishing it from contact_restore and permanent deletion. The parenthetical 'can be restored later' further clarifies the tool's unique role.

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

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

The description implies use when a reversible deletion is desired, and the mention of restore later aligns with the contact_restore sibling. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of full guidance.

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

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

No annotations are present, so the description carries the burden. It discloses the matching criteria (name, email, phone) and the output (pairs with reasons), which gives the agent a clear picture of expected behavior. The word 'scan' implies a non-destructive read operation, but it does not explicitly state that no data is modified, nor describe any limits or edge cases.

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

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

The description is two sentences long, directly front-loaded with the main action, and every word contributes value. No redundant information.

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

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

For a zero-parameter tool with no output schema, the description is complete: it explains the action, the matching methods, and the return format. The only minor gap is the lack of an explicit statement about global scope or read-only behavior, but 'scan' and 'returns' convey this adequately.

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

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

The tool has zero parameters, so the description does not need to explain parameter semantics. According to the rubric, the baseline is 4; the description appropriately omits any parameter details.

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

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

The description clearly states the tool 'Scan for potential duplicate contacts' using name, email, and phone matching, which is a specific verb + resource + method. It distinguishes itself from sibling tools like contact_merge (which would act on duplicates) and contact_list (which lists all contacts).

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

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

There is no explicit guidance on when to use this tool vs alternatives. The purpose implies deduplication workflows, but it does not mention that this should precede contact_merge or that it scans the entire contact database. Lacks exclusions or alternative references.

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

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

With no annotations, the description carries the full disclosure burden. It lists broad return categories (contact methods, activities, gifts, debts), which is helpful, but it omits behavioral details such as the definition of 'recent', whether empty lists are omitted, or inherent performance/authorization implications for a heavy aggregate call.

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

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

The description is one sentence with a strong front-loaded purpose, followed by a long list of data types. The list is necessary to convey the aggregate scope, so the length is justified and the structure reads efficiently.

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

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

Without an output schema, the description compensates by enumerating 14 categories of returned data, giving a solid expectation of the response. The single required parameter is simple, and the description is largely complete, though caveats about empty lists or the meaning of 'recent' could add further clarity.

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

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

The input schema already provides a 100% description for the only parameter, contact_id, so the baseline is 3. The description adds no extra semantics beyond indicating that the returned details belong to the specified contact.

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

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

The description uses a specific verb ('Get') and resource ('full contact details') while enumerating the exact data categories included, making its purpose unmistakable. It clearly distinguishes itself from sibling tools like contact_list (which likely returns summaries) and domain-specific getters like food_preferences_get.

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

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

The phrase 'including all related data in one call' provides clear context for when to use this tool—when a complete contact snapshot is needed, avoiding multiple sibling calls. It does not explicitly list exclusions or alternatives, but the usage intent is clear.

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

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

With no annotations, the description carries the transparency burden. It discloses that results are paginated, which is a behavioral trait not explicit in the schema. However, it does not mention default filtering of archived/deleted contacts or any access limitations, leaving 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.

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

The description is extremely concise—two sentences with all words earning their place. It front-loads the primary action and includes the most relevant behavioral detail (pagination) without redundancy.

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

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

For a list tool with 10 parameters and no output schema, the description covers the essential behavior: listing contacts with filters and paginated results. The schema fills in all parameter details, and the tool's purpose is unambiguous. It could mention default sort order or that soft-deleted contacts are excluded by default, but those are in the schema already.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists several filter fields (status, favorite, company, tag, search) but adds little beyond the schema's own parameter descriptions. The pagination mention provides context, but not parameter-level syntax.

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

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

The description clearly states 'List contacts' with a specific verb and resource, and mentions optional filters and pagination. This distinguishes it from single-record tools like contact_get and other list tools like note_list, though it does not explicitly name alternatives.

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

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

No guidance is provided about when to use this tool versus alternatives such as contact_get or contacts_needing_attention. The description only describes the function without exclusions, prerequisites, or recommended contexts.

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

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

No annotations are provided, so the description carries the burden. It discloses key side effects: child records are moved and the secondary contact is soft-deleted. Yet it omits important behavioral details such as conflict resolution, whether the primary is modified beyond receiving child records, reversibility, and any return value or failure modes.

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

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

The description is two sentences long, front-loads the purpose with 'Merge two contacts into one,' and each subsequent clause adds meaningful information about child record movement and soft-deletion. There is no filler or redundancy.

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

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

For a two-parameter merge operation with no output schema and no annotations, the description covers the core functionality and side effects. However, it is incomplete regarding the return value, error conditions, and whether the operation is reversible (e.g., via contact_restore). These gaps leave some uncertainty for an agent invoking the tool.

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

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

The input schema already provides descriptions for both parameters (primary vs. secondary, with soft-delete noted for the secondary), achieving 100% coverage. The tool description restates this semantics but adds no new parameter-specific detail beyond what the schema already explains, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Merge') and identifies the resource ('two contacts'), clearly differentiating it from siblings like contact_delete or contact_update. It also specifies the scope of the operation by stating that all child records from the secondary contact are moved to the primary, 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.

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

The description clearly implies the typical use case—consolidating duplicate contacts—by detailing the merge behavior and the soft-deletion of the secondary contact. However, it does not explicitly state when to prefer this tool over alternatives like contact_delete or contact_find_duplicates, nor does it provide exclusions or preconditions.

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

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

No annotations are provided, so the description carries the full burden. It merely states the actions without disclosing side effects, the need for IDs, validation behavior, or whether removal is hard/soft. This is a mutation tool and the description does not communicate any of these 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.

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose with no redundant words.

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

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

The schema covers parameter semantics, but the description lacks guidance about action-specific requirements and preconditions. With no output schema and no annotations, the description does not fully equip an agent to handle the tool's conditional logic (e.g., id required for update/remove). 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.

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

The schema has 100% description coverage for all 7 parameters, so the schema already provides the parameter meanings. The description adds nothing beyond repeating type examples (email, phone, social handle) which are already in the 'type' property description. Baseline 3 is appropriate.

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

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

The description clearly states the exact operations ('Add, update, or remove') and the resource ('contact method'), with illustrative types. This distinguishes it from sibling contact tools like contact_update/contact_create, which operate on the contact record itself, not contact methods.

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

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

Usage is implied: to manage contact methods. However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description does not mention that 'add' requires contact_id or that 'update'/'remove' require id, though these are in the schema.

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

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

With no annotations, the description must disclose side effects, reversibility, and error conditions. It only states the action, adding no context about what happens on success/failure, whether restore is reversible, or if permissions are needed. This is a significant gap 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.

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

The description is a single, front-loaded sentence with no waste. It communicates the essential action and resource directly.

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

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

The tool has no output schema and no annotations, so the description bears full responsibility for usage context. While the action and input are clear, it omits expected outcomes, preconditions, and behavior for invalid IDs, leaving the agent under-informed for a mutation operation.

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

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

The only parameter contact_id is fully described in the schema with 'The contact ID to restore', matching the description's context. Since schema coverage is 100%, the description adds no additional semantic value beyond the schema.

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

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

The description clearly states the tool's action ('Restore') and target ('a soft-deleted contact'), distinguishing it from sibling tools like contact_delete and contact_create. It uses a specific verb and resource, making the purpose unambiguous.

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

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

The description implies usage when a contact has been soft-deleted, but provides no explicit guidance about when to choose this over contact_create or contact_update, nor conditions like hard-deleted contacts. This is implied usage, not explicit guidance.

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

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

With no annotations provided, the description carries the full burden. It explains key behaviors like sorting by staleness (longest since last interaction first) and including zero-interaction contacts first. It does not explicitly state read-only semantics, but the verb 'Find' implies it. The description adds meaningful 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.

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

The description is two sentences, front-loads the core purpose, and adds essential behavioral details without any fluff. Every word earns its place.

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

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

Given 5 optional parameters, no output schema, and no annotations, the description covers the main behavioral promise (staleness sorting, zero-interaction inclusion) but doesn't describe the return shape or how filters interact. However, the schema covers the parameters, and the description is sufficient for core understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not directly elaborate on the parameters but implicitly conveys how the staleness filter works via the sorting and inclusion behavior. It doesn't add syntax or format details, so it meets the baseline without exceeding it.

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

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

The description clearly states the tool's purpose with a specific verb 'Find' and resource 'contacts you haven't interacted with recently'. It also provides concrete details about sorting by staleness and inclusion of zero-interaction contacts, which clearly differentiates it from siblings like contact_list or contact_timeline.

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

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

The description sets clear context with the phrase 'the "who am I neglecting?" query', implying when to use it. However, it does not explicitly mention alternatives or exclusions, such as pointing to contact_list for a full list, so it misses the highest bar.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as read-only status, sorting order, pagination behavior, or what happens when no entries exist. The only behavioral hint is 'unified', but this is insufficient for a tool with 4 parameters.

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

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

The description is a single, front-loaded sentence that states the core action and resource without wasted words. It is appropriately concise and well-structured.

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

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

The tool has 4 parameters, no output schema, and no annotations, but the description does not explain pagination, filtering, or the return format. It only gives a vague sense of the result ('unified timeline'). This is inadequate for effective use.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds no additional parameter semantics beyond what the schema provides, hence a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get the unified timeline for a contact' and lists examples (activities, life events, notes, etc.). This specific verb-resource pair distinguishes it from sibling tools like activity_list and note_list, which focus on single entry types.

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

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

The word 'unified' implies this is for viewing multiple entry types together, but the description provides no explicit guidance on when to use this tool versus specific siblings like activity_list or note_list, nor any exclusions. Usage context is only implied.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It only says 'Update contact fields' and does not mention side effects, permission requirements, partial update semantics, or what the response contains. This is a significant gap 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.

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

The description is a single concise sentence with no wasted words. While it is brief, it directly states the core purpose and is appropriately front-loaded for a tool that receives most of its detail from the schema.

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

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

Despite having 24 parameters, no output schema, and no annotations, the description provides almost no context. It does not explain how updates work (e.g., partial update, required contact_id, field dependencies), leaving the agent to infer critical invocation details solely from the schema.

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

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

The input schema documents all 24 parameters, each with a description, so schema coverage is 100%. The tool description itself adds no parameter-level detail, but the structured schema already provides the necessary semantic coverage, warranting a baseline score of 3.

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

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

The description 'Update contact fields' clearly states the action (update) and the resource (contact fields), making the tool's purpose evident. However, it does not explicitly differentiate itself from sibling tools like contact_merge or contact_restore, which also modify contact-related data.

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

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

There is no guidance about when to use this tool versus alternatives such as contact_create or contact_merge. The description lacks any context about prerequisites, typical use cases, or scenarios where this tool should or 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.

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 behavioral disclosure. It only restates the actions without explaining side effects (e.g., whether 'remove' is permanent, whether 'update' overwrites existing values), permissions needed, or impact on the contact. This is a significant gap 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.

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

The description is a single, concise sentence that lists all actions. It is front-loaded and contains no filler. Every word earns its place.

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

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

This is a multi-action tool with 6 parameters, no output schema, and no annotations. The description is too sparse to be complete: it does not explain differences between actions, potential side effects, return values, or error conditions. The schema covers parameter requirements but not behavioral context, leaving the description insufficient for safe invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it does not elaborate on parameter relationships or provide examples. The schema's conditional requirements (e.g., 'required for update/remove') are already documented, so the description neither helps nor hurts.

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

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

The description clearly states the tool's function: 'Add, update, or remove a custom field on a contact.' It uses a specific verb list (add/update/remove) and identifies the resource (custom field on a contact), distinguishing it from sibling tools like contact_update or contact_create.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or scenarios where another tool (e.g., contact_update for standard fields) would be more appropriate. The schema hints at conditional requirements, but the description itself offers no usage context.

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

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

No annotations are provided, so the description must disclose behavioral traits. It does not state whether the operation is read-only, any rate limits, authentication requirements, or response structure beyond 'JSON object'. This lack of behavioral context could leave an agent uncertain about side effects or constraints.

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

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

The description is a single sentence that is front-loaded with the core action ('Export all CRM data as a JSON object') and then lists included data types. It is concise, scannable, and contains no redundant or filler content.

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

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

The description adequately states what is exported and the format, but it does not describe the JSON structure (e.g., whether it is a flat object with arrays per category) or any constraints like size limits or pagination. Since there is no output schema, this missing information leaves some gaps for an agent using the tool.

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

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

The tool has zero parameters, and the input schema is empty. With no parameters, there is nothing to document, and the description correctly adds no parameter-specific information. Baseline of 4 applies because parameter semantics are trivially satisfied.

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

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

The description clearly states the tool exports all CRM data as a JSON object, listing specific data categories (contacts, relationships, notes, etc.). This specific verb+resource combination distinguishes it from siblings like data_statistics (statistics) or contact_list (individual contacts).

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

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

The description implies usage for full-dataset export, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. For example, it does not say 'for individual records use contact_list' or 'for statistics use data_statistics'. The usage context is clear but not explicitly contrasted with other tools.

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

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

With no annotations, the description carries the burden of disclosing behavior. It conveys that this is a read-only summary operation and lists the types of information returned. However, it does not mention authentication requirements, data scope (e.g., global vs. user-specific), freshness, or response structure beyond the vague 'etc.'.

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

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

The description is a single, front-loaded sentence that immediately names the action and scope, followed by parenthetical examples to clarify without adding unnecessary length.

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

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

For a no-input, read-only statistics tool, the description is reasonably complete: it identifies the tool's purpose and the main output categories. The lack of an output schema and annotations means the description could be more explicit about exact returned fields, but the simple nature of the tool lowers that burden.

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

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

The tool has zero parameters, so the baseline is 4. The description adds useful context about what data categories the output will cover, which is the only semantic layer needed.

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

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

The description uses a specific verb ('Get') and a clear resource ('CRM statistics and overview'), with concrete examples of what is included (contact counts, activity counts, pending items). This clearly distinguishes it from sibling tools that list individual contacts or activities.

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

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

The description implies this tool is for aggregate overviews and counts, not detailed lists, but it does not explicitly state when to prefer this over sibling tools like contact_list or activity_list. The context is clear enough for a simple read-only summary tool.

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

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

With no annotations, the description carries the full burden and does disclose key behaviors: "Soft-delete" for delete, "restore" for soft-deleted debts, and "include_deleted" for listing. Yet it omits important side effects like whether settle changes status, how update handles partial fields, or any permission requirements. It gives basic behavioral clues but not a comprehensive safety or mutation profile.

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

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

The description is a concise, well-structured bullet list with a front-loaded summary sentence. Every bullet is functional and adds necessary information about an action and its requirements. There is no filler or redundancy, making it easy to scan and understand.

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

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

For a multi-action tool with 12 parameters and no output schema, the description covers every action, its purpose, and required parameters, which is largely complete. It falls short of full completeness by not describing return values or error/edge-case behavior, but the action-oriented guidance is strong enough to make the tool usable without excessive guesswork.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little semantic value beyond the schema itself, mostly restating which parameters are required per action (already present in each parameter's description). It does consolidate per-action requirements into a readable format, but it does not introduce new meanings for parameters themselves.

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

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

The description opens with a specific verb+resource statement: "Create, list, update, settle, delete, restore, or summarize debts." This covers all actions and clearly distinguishes the tool as the debt-management resource among many resource-specific siblings (e.g., gift_manage, note_manage, task_manage). The bullet list further reinforces the exact scope for each action.

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

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

Each action bullet provides when to use it and required parameters, such as "action='create': Track a new debt. Requires contact_id, amount, direction." This gives clear context for selecting the appropriate action. However, it does not explicitly contrast with alternative tools (e.g., 'use activity_list for transactions'), so it lacks explicit exclusions or when-not-to-use guidance.

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

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

No annotations are present, so the description carries the burden of behavioral disclosure. It does add value by specifying the categories returned, but it does not disclose return structure, error behavior (e.g., if contact not found), or whether all categories are always populated. It is not contradictory.

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

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

The description is a single, front-loaded sentence with no fluff. The parenthetical examples provide necessary context without wasting words.

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

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

With one simple parameter and no output schema, the description provides the tool's purpose and content categories but does not explain the return format or edge-case behavior (e.g., empty preferences, missing contact). It is adequate for a simple get but not comprehensive.

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

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

The schema already describes contact_id as 'The contact ID', providing 100% coverage. The description adds no additional parameter meaning beyond the generic 'for a contact', so it does not exceed the schema baseline.

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

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

The description uses a specific verb 'Get' and a clear resource 'food preferences for a contact', and lists the categories included (dietary restrictions, allergies, favorites, dislikes). This distinguishes it from the sibling tool food_preferences_upsert (the write counterpart) and other contact-related retrieval tools.

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

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

The description implies when to use the tool (when you need a contact's food preferences) but provides no explicit guidance on when not to use it or how it compares to alternatives like food_preferences_upsert. There are no alternative tool mentions or exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses the critical behavior that all fields are replaced, preventing accidental data loss. It does not mention side effects like contact creation or return values, but the core overwrite risk is clearly communicated.

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

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

Two sentences, front-loaded with the main action, and every word adds value. No redundancy or filler.

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

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

The description adequately covers purpose, usage pattern, and an important behavioral trait for a moderately simple mutation tool. It could mention behavior for invalid contact_id or empty arrays, but for typical use the information is sufficient.

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

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

Schema coverage is 100% so the baseline is 3. The description adds semantic meaning beyond the schema by stating 'Replaces all fields', which clarifies that the parameter arrays (favorite_foods, allergies, etc.) are written as a complete set rather than merged or patched.

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

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

The description clearly states the tool 'Set or update food preferences for a contact' with a specific verb (set/update) and resource (food preferences). It also distinguishes from its sibling food_preferences_get by implying a write operation, and highlights the key 'Replaces all fields' behavior.

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

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

Provides explicit usage guidance: 'pass all known preferences, not just changes' tells the agent how to invoke the tool correctly for a full overwrite. However, it does not explicitly compare to alternative tools like food_preferences_get, so it lacks a clear when-not-to-use clause.

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

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

No annotations means the description carries the burden. It discloses filtering and summary stats, but does not explicitly state read-only behavior, pagination details, or exactly what the summary stats include. 'List' implies a safe read operation, but more behavioral detail would help.

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

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

Two sentences, front-loaded with the core purpose. Every clause adds meaningful guidance—filter options, special mode, and sort hints—with no wasted words.

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

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

For a 9-parameter tool with no output schema, the description explains the main purpose and a special mode, but does not describe the return structure beyond 'summary stats,' nor pagination or soft-delete behavior. It is adequate for basic use but leaves gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by noting that omitting contact_id switches to a cross-contact tracker with summary stats, which is not evident from the schema alone. It also highlights sort_by and sort_order, reinforcing their relevance.

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

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

The description opens with 'List gifts,' a specific verb and resource, and immediately clarifies optional filters (contact, status, direction). The added note about omitting contact_id for a cross-contact gift tracker with summary stats distinguishes this from sibling tools like contact_list and gift_manage.

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

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

The description gives clear usage context: filters, sorting, and the two modes (contact-specific vs. cross-contact tracker). It does not explicitly name alternative tools for mutation, but the 'List' verb and filter options imply appropriate usage well.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal the key nuance that delete is a soft-delete, which is valuable. However, it does not describe return values, error cases, or how updates handle unspecified fields. The soft-delete disclosure is a plus, but the overall behavioral coverage is still limited.

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

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

The description is exceptionally well-structured: one opening sentence stating the tool's scope, followed by four bullet points, each for a distinct action with condensed parameter requirements. Every sentence serves a purpose, there is no fluff, and the format makes it easy for an agent to scan and act on quickly.

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

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

This is a multi-action mutation tool with no annotations and no output schema, but the description covers all the essential usage contexts for each action: required fields, optional fields, and even the soft-delete behavior. It is nearly complete for the complexity involved, though it could mention expected return values or error scenarios to be fully complete.

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

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

The input schema has 100% description coverage, so the schema already documents every parameter's meaning and constraints. The description repeats this information but organizes it by action, which adds some clarity (e.g., which params are required for create vs. update). However, it does not add new semantic information beyond what the schema already provides, so it remains at the baseline for high coverage.

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

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

The description explicitly states the primary verb+resource: "Create, update, delete, or restore a gift for a contact." This clearly distinguishes it from sibling tools like gift_list (which lists gifts) and other manage tools for different resources. The action breakdown further clarifies the exact scope of the tool.

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

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

The description provides clear context for each action, listing required and optional parameters for create, update, delete, and restore. However, it does not explicitly compare this tool to alternatives or state when NOT to use it (e.g., vs. gift_list for viewing). The action-specific guidance is strong, but the absence of exclusionary guidance prevents a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses the return behavior (grouped results by entity type, snippets, contact context), which is valuable. It does not mention pagination, defaults, or side effects, but for a read-only search tool, the description is reasonably transparent.

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

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

The description is one well-structured sentence that front-loads the purpose and then lists scope and output highlights. It is concise with no filler, earning a top score for efficiency.

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

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

Given the absence of an output schema and annotations, the description effectively communicates the return format and scope. It does not mention default parameter values, but those are covered in the schema. Overall, it provides sufficient context for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds context about the query scope ('in a single query') but does not provide additional meaning for the entity_types or limit_per_type parameters beyond what the schema states. Thus a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Search') and resource ('all entity types'), and explicitly lists the entity types covered. It clearly distinguishes itself from sibling list/manage tools that focus on single entity types, making the tool's cross-entity purpose unambiguous.

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

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

The description implies usage for cross-entity search in a single query, which is a clear context. However, it does not explicitly state when not to use this tool or mention alternative tools like contact_list or note_list for single-type searches. The guidance is strong but not exhaustive.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly mentions 'Soft-delete' for delete and 'Restore a soft-deleted life event' for restore, and the list action documents include_deleted. It does not discuss permissions, side effects, or return values, but the soft-delete semantics are a key behavior disclosed beyond simple CRUD.

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

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

The description is front-loaded with the main purpose, followed by succinct, bullet-style action breakdowns. Each sentence earns its place, and the structure allows quick scanning of all five actions and their parameter requirements without unnecessary verbosity.

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

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

For a complex multi-action tool with no output schema, the description covers all input parameters and per-action requirements, including soft-delete behavior. It does not explain return values or error conditions, which could be a gap, but the overall input-side guidance is comprehensive enough 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.

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

Despite 100% schema coverage, the description adds significant value by grouping parameters per action and stating requirements (e.g., 'Requires contact_id, event_type, and title' for create). This clarifies parameter combinations that the schema alone does not explicitly define, making tool invocation much more straightforward.

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

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

The description opens with 'Create, list, update, delete, or restore life events for a contact,' which uses a specific verb set and clearly identifies the resource (life events). This distinguishes it from sibling tools like activity_manage or note_manage, which handle different entities.

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

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

The description provides action-specific guidance, stating exactly which parameters are required for each action. It implicitly communicates when to use the tool (for life event management) and differentiates from siblings by resource type. It does not explicitly name alternatives or exclusions, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool opens a browser page and enables/disables web push notifications, which is useful. However, it does not mention whether this is a direct mutation or requires user interaction, nor does it address prerequisites like browser availability. The behavior is partially transparent but not fully detailed.

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

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

The description is two sentences, immediately front-loaded with the action ('Open a page'), and contains no redundant information. Every word adds value, and it does not repeat tool name or schema details.

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

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

For a simple, parameterless UI-tool with no output schema, the description is largely complete: it states what happens (opens page) and the purpose (manage subscriptions). It could mention limitations (e.g., requires a browser or user interaction), but given the low complexity and absence of output schema, the description covers the essential context sufficiently. A score of 4 reflects minor gaps in behavioral detail.

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

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

The tool has zero parameters and the schema coverage is 100% (no properties). The description does not need to add parameter details. It does mention the scope ('birthday reminders and other alerts'), which adds context beyond the empty schema, so a baseline of 4 is appropriate.

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

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

The description clearly states the tool opens a page to manage push notification subscriptions, with a specific verb ('Open'), resource ('push notification subscriptions'), and scope ('birthday reminders and other alerts'). This distinguishes it from sibling tools like notification_list or notification_create, which handle individual notifications rather than subscription preferences.

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

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

The description implies usage for managing web push notification subscriptions but does not explicitly state when to use this tool versus alternatives like notification_list or manage_settings. No exclusions or comparative guidance is provided, making the context clear but leaving the decision to the agent.

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

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

No annotations are provided, so the description carries the full burden. It explains the read vs. write behavior (get vs. update) and indicates update is partial via optional fields. However, it does not disclose return value format, permission requirements, or side effects (e.g., whether omitted fields are preserved). This is adequate but not rich, aligning with a mid-range score.

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

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

The description is well-structured with a clear opening sentence followed by bullet-pointed action definitions. It is concise yet comprehensive, with no redundant filler. Every sentence adds useful information, making it easy to scan and process.

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

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

Given 5 parameters (1 required) and no output schema, the description covers the action semantics and parameter details thoroughly. The only gap is the lack of explicit return value information for get/update, but the tool's behavior is otherwise well outlined. It is near-complete for a settings management tool.

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

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

The schema already covers 100% of parameters (baseline 3). The description adds value by explaining the action enum and clarifying the meaning of offset arrays ('0=day-of, 7=week-before') and distinguishing between birthday reminder offsets and custom reminder offsets. It provides examples that make parameter usage more concrete than the schema alone.

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

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

The description clearly states the tool views or updates personal settings, with specific sub-fields (timezone, birthday reminder preferences). It distinguishes from sibling tools like reminder_manage by focusing on settings rather than individual reminders/notifications. The action enum is explicitly linked to purpose, making the tool's function unambiguous.

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

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

The description provides clear context on when to use the tool (for viewing/updating personal settings) and explains the two action modes. It does not explicitly mention alternatives or exclusions, but the domain ('personal settings') is sufficiently distinct from sibling tools to guide selection. A clear context is given, just no explicit 'don't use for X'.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds meaningful behavior beyond the schema: pinned-first ordering and the subtle mode switch when additional filters are added. It omits details like include_deleted behavior, but those are present in the schema.

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

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

Two sentences, front-loaded with the core purpose, and every word earns its place. No fluff or repetition of schema details.

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

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

For a 9-parameter list tool with no output schema and no annotations, the description covers the essential behavioral modes and search semantics. Pagination and sort defaults are left to the schema, which is acceptable, though return format is not described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantics for contact_id, clarifying that it only applies when used alone, and explains that query/tag_name/is_pinned shift to global search. This goes beyond schema descriptions.

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

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

The description clearly states the tool 'List and search notes' with a specific verb and resource. It also distinguishes two behavioral modes (contact-specific vs global search) and naturally differentiates from sibling tools like note_manage.

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

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

The description provides clear context on parameter combinations: contact_id alone lists that contact's notes; adding query, tag_name, is_pinned, or omitting contact_id searches across all contacts. It does not explicitly name alternatives or exclusions, hence not a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses important behavior such as 'soft-delete' and the restore capability, which is useful. However, it does not describe return values, error handling, or side effects beyond the action semantics, 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.

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

The description is concise and well-structured with a leading summary followed by a bullet list for each action. Every sentence provides essential information, and the format makes it easy to parse.

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

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

Given the multi-action complexity and lack of annotations/output schema, the description covers the essential usage guidance for all four actions, including parameter dependencies. It omits some details like return values or error responses, but the core operational context is sufficiently complete for correct tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explicitly mapping each action to required and optional parameters (e.g., create requires contact_id and body), which is more actionable than the schema's individual parameter descriptions alone.

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

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

The description clearly states 'Create, update, delete, or restore a note for a contact,' using a specific verb and resource. It enumerates all four actions, distinguishing it from sibling tools like note_list.

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

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

The description provides clear per-action usage instructions, noting which parameters are required and optional for each action. It does not explicitly mention when to use alternatives like note_list, but the action-oriented bullets give unambiguous context for when to invoke this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'create', implying a mutation, but fails to mention side effects, permission requirements, or response behavior. This is a significant gap for a create operation.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the verb and resource, making the core action immediately clear. This is an example of effective conciseness.

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

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

The tool has a simple schema with full parameter coverage, and no output schema exists. However, the lack of annotations and the minimal description leave gaps around return values, side effects, and when this tool is appropriate. 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.

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

The input schema has 100% description coverage for all four parameters, so the schema already documents them fully. The description adds no additional parameter semantics beyond the word 'custom', which aligns with the baseline of 3.

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

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

The description clearly states the action 'Create' and the resource 'notification', which is specific. It distinguishes from sibling tools like notification_list and notification_read by the create verb, but 'custom' adds slight ambiguity as to whether it differs from other notification creation mechanisms.

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

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

The description provides no guidance on when to use this tool versus alternatives such as manage_push_notifications or reminder_manage. It implies usage for creating a notification but lacks any exclusionary or contextual information, leaving the agent to infer applicability.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds the 'newest first' ordering detail, which is useful, but it does not mention potential side effects (e.g., whether listing marks notifications as read) or pagination behavior. For a simple read operation this is acceptable 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.

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

The description is a single sentence, front-loaded with the core action, and contains no redundant words. Every word earns its place.

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

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

The tool is a simple list operation with pagination and filtering, and the schema covers all parameters. However, there is no output schema and the description does not mention return format or pagination defaults, leaving minor gaps. It is minimally adequate but not comprehensive.

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

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

The input schema already describes all three parameters (page, per_page, unread_only) with 100% coverage. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description 'List notifications (newest first)' uses a specific verb and resource, and the ordering detail adds scope. It is clear and distinct from siblings like notification_create and notification_read, though it does not explicitly call out those alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives such as activity_list or note_list. It only states the basic action without any context for selection.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It states the core action (marking as read) and the two operational modes, which is adequate. However, it does not mention whether the action is reversible, any permission requirements, or the effect on unread counts, which would be useful 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.

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

The description is exceptionally concise: two sentences, front-loaded with the action, and no wasted words. Every phrase carries meaning.

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

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

For a simple two-parameter tool with no output schema, the description covers the primary usage modes. It is slightly incomplete in that it does not address what happens if both id and all are supplied or the nature of the response, but these are minor gaps for such a straightforward operation.

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

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

Schema coverage is 100%, so the schema already explains both parameters. The description adds a convenience hint ('Pass id for a single notification, or all=true for all') that reinforces the conditional relationship, but it duplicates the 'required unless all=true' note already in the id property description. Minimal added value beyond the schema.

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

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

The description uses the specific verb 'Mark' and targets the resource 'notification(s) as read,' which clearly distinguishes this from sibling tools like notification_list (listing) and notification_create (creating). The phrase 'as read' eliminates ambiguity between reading/retrieving and marking-as-read.

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

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

The description explicitly explains the two usage modes: pass an id for a single notification or use all=true for all. It gives clear context on how to invoke the tool, but does not explicitly mention exclusions or alternatives; however, the intended use is self-evident from the sibling set.

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

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

No annotations are provided, so the description fully discloses the behavior: it returns a compact overview with user identity, all tags, 200 recent contacts, and 10 recent notes. It also explains the purpose of this data for context priming, providing transparency beyond the empty schema.

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

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

The description is three sentences, front-loaded with the critical instruction to call first. It conveys all necessary information without waste.

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

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

For a zero-parameter priming tool with no output schema, the description fully covers what the tool returns, when to call it, and why it's beneficial. It is complete for the agent's context.

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

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

The tool has zero parameters, so the schema provides no semantics. The description appropriately doesn't need to explain parameters. Baseline for zero parameters is 4, and no additional parameter detail is required.

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

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

The description clearly states the tool's purpose: to be called first to load essential CRM context, returning a specific compact overview. It distinguishes itself from sibling list tools by positioning as a primer that avoids separate list calls.

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

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

It explicitly instructs to call this tool first before any other tool and at the start of a conversation. It implies alternatives by saying 'without needing separate list calls,' but does not explicitly name alternative tools or contrast with specific siblings for when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals key side effects: automatic inverse relationship creation/update/removal, the requirement to use a prime tool ID for self-relationships, and the acceptance of custom relationship_type values from Settings. These insights go beyond the schema and help the agent understand the tool's consequential behavior. However, it omits permissions, reversibility, or response format, so a 4 is appropriate rather than 5.

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

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

The description is well-structured with bullet points for each action, making it easy to scan. The opening sentence states the core purpose, and each bullet contains essential information without fluff. It is slightly verbose due to repeating action prefixes, but every sentence earns its place, so a 4 is warranted rather than 5.

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

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

The description covers all four actions, required parameters, inverse behavior, self-contact handling, and relationship types. For a tool with this complexity (4 actions, 6 parameters) and no output schema, it is largely complete. Minor gaps like error conditions or response format do not significantly impact usability, but given the lack of annotations, a 4 is fitting.

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

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

While the schema already documents all 6 parameters with 100% coverage, the description adds action-specific parameter semantics (e.g., which params are required for each action) and clarifies that notes are optional for add/update. It also explains that relationship_type includes canonical values plus custom values, enriching the parameter meaning beyond the schema's description. This added value justifies a 4, above the baseline of 3.

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

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

The description opens with a specific verb+resource: 'Add, update, remove, or list relationships between contacts.' It clearly defines the tool's scope and distinguishes it from sibling tools (e.g., contact_update, tag_manage) by focusing on relationships. The example 'Bandit is Bingo's parent' further clarifies the semantic intent, making the purpose unambiguous.

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

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

The description offers detailed action-specific guidance, listing required parameters for each action (add, update, remove, list). It also includes a specific instruction for creating relationships involving yourself ('use your own contact_id from the prime tool'). While it doesn't explicitly compare with alternative tools, the action breakdown provides clear when-to-use context, earning a 4.

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

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

With no annotations, the description carries the full burden and does well by disclosing key behaviors: it notes that delete is a soft-delete, restore exists, and 'complete' advances recurring reminders to the next occurrence. It also hints at soft-delete behavior via the 'include_deleted' parameter. Missing details like return values or error handling, but those are not required given no 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.

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

The description is a front-loaded summary followed by a tight bullet list, one per action. Every sentence is directly useful, no fluff or repetition. It is well-structured with consistent formatting, making it easy to scan and understand.

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

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

For a tool with 7 actions, 12 parameters, no annotations, and no output schema, the description covers all actions and parameter requirements, including edge cases like soft-delete and recurrence. It stops short of explaining pagination defaults beyond naming 'page' and 'per_page', but those are in the schema. Overall, it is complete enough for an agent to select and invoke the tool correctly for most scenarios.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning by mapping parameters to specific actions (e.g., contact_id is 'required for create, optional filter for list'). It also clarifies the semantics of frequency and the recurring reminder behavior on 'complete', which goes beyond the schema's straightforward descriptions. This helps an agent construct valid requests per action.

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

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

The description opens with 'Create, list, update, complete, snooze, delete, or restore reminders,' which specifies the exact verbs and resource, making it clearly distinct from sibling tools like task_manage or activity_manage. Each action is enumerated with precise scope, leaving no ambiguity about what the tool does.

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

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

The description provides clear context for when to use each action by pairing them with required parameters (e.g., 'Requires id and new_date' for snooze). While it doesn't explicitly name alternative tools or exclusion criteria, the action-specific breakdown gives an agent enough guidance to select the right action and avoid misuse. Sibling tools target different resources, so the intended usage is implied.

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

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

With no annotations, the description carries the full transparency burden. It discloses useful idempotency behaviors such as 'Create a new tag (or return existing if name already exists)' and 'Creates the tag if it doesn't exist' for tag_contact. However, it does not mention return values, permissions, or side effects of delete/update, 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.

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

The description is well-structured with a short intro and bulleted actions, each earning its place with specific requirements. It is appropriately sized for a multi-action tool, though some bullet details duplicate the schema descriptions, making it slightly less concise than ideal.

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

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

The description covers all six actions and their parameter requirements, which is the core of what an agent needs. However, with no output schema and no mention of return values or error conditions, the description is not fully complete for an agent to anticipate the tool's response, especially for actions like delete and update.

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

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

Schema description coverage is 100%, so the schema already explains each parameter's purpose and required actions. The description reinforces these mappings in the bullets but adds no additional meaning beyond what the schema provides, such as format or constraints.

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

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

The description clearly states 'Manage tags and contact tagging' and enumerates six specific actions with their required fields. This distinguishes it from many siblings by showing it covers the full tag lifecycle, but it does not explicitly differentiate itself from the closely related 'batch_tag_contacts' tool.

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

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

The description provides per-action instructions but no guidance on when to choose this tool over alternatives like 'batch_tag_contacts' or other tag-related tools. There are no explicit when-not-to-use or exclusion statements, leaving the model to infer the appropriate context from the action list alone.

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

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: delete is 'Soft-delete' and restore is for 'soft-deleted' tasks, with list supporting include_deleted. It does not mention return values or error conditions, but the disclosed behaviors are meaningful 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.

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

The description is compact and well-structured with a summary line followed by six focused bullets. Every sentence adds actionable information with no fluff or redundancy.

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

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

The description fully covers all six actions, their required/optional params, and soft-delete behavior. However, with no output schema, it omits expected return values or success/failure indicators, leaving a minor gap for agents needing response context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by organizing parameters under each action, clarifying which are required for specific operations (e.g., 'delete' requires id, 'create' requires title). This action-level grouping goes beyond the flat schema descriptions.

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

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

The opening line 'Create, list, update, complete, delete, or restore tasks' uses specific verbs and a clear resource, fully describing the tool's scope. The action enum distinguishes it from sibling tools like contact_update or note_manage, making its uniqueness obvious.

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

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

Each action bullet lists its required and optional parameters, providing clear when-to-use guidance for each sub-operation. The description does not explicitly mention alternatives or exclusions relative to sibling tools, but the action-based structure effectively communicates usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable details: 'Returns contacts sorted by soonest birthday first, with age calculations when available.' This explains sorting and return behavior. However, it does not disclose the precedence rule when both month and days_ahead are provided (though the schema does). Given no annotations, this is a strong behavioral description 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.

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

The description is two sentences with no redundant or irrelevant information. It front-loads the primary purpose and then adds key behavioral details (sorting, age). Every word earns its place, and it is appropriately sized for the tool's simplicity.

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

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

Given there is no output schema and no annotations, the description must convey return behavior, which it does ('Returns contacts sorted... with age calculations'). It covers the main use cases (time window or month) and the key output aspect. It could be more complete by mentioning what happens in edge cases (e.g., contacts without birthdays), but for a simple query tool, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's phrase 'time window' and 'specific month' paraphrases the parameter meanings but adds no additional semantic detail beyond what the schema already provides. The default value for days_ahead (30) is only in the schema, not the description. Thus, the description neither improves nor detracts from parameter clarity.

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

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

The description clearly states the tool's function: 'Find contacts with birthdays coming up within a time window or in a specific month.' This uses a specific verb (Find), a clear resource (contacts), and a distinguishing scope (birthdays within a time window/month). It also differentiates from sibling tools like contact_list and upcoming_reminders by focusing specifically on birthdays.

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

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

The description implies when to use the tool: when you need contacts with upcoming birthdays, either within a date range or for a specific month. It provides clear context but does not explicitly mention alternatives or when not to use it. For example, it doesn't say 'use contact_list for all contacts' or 'use upcoming_reminders for reminders.' This is clear usage context without explicit exclusions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It reveals the global scope ('across all contacts') and the sorting behavior (overdue first, then upcoming). While it doesn't explicitly say 'read-only,' the verb 'Find' and 'Returns' strongly imply a safe, non-mutating operation. This is adequate for a read/list tool.

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

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

The description is two sentences long, front-loaded with the primary purpose, and every clause adds value. It avoids unnecessary detail and is immediately scannable.

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

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

For a simple list/read tool with no output schema, the description covers the key context: purpose, scope, and sort order. The optional parameters are well-documented in the schema, so the description doesn't need to restate them. It falls short of 5 only by not explicitly noting read-only behavior or defining 'overdue,' though the schema partially covers the latter.

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

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

Schema description coverage is 100%, so the input schema already fully documents status, days_ahead, and include_overdue. The description adds no extra parameter-specific semantics, leaving the schema to carry the load—which it does effectively.

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

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

The description clearly states the tool's purpose: finding upcoming and overdue reminders across all contacts. The specific verb 'Find' and the resource 'reminders' make the action unambiguous, and the added detail about sorting (overdue first, then soonest upcoming) distinguishes this from reminder management tools like reminder_manage and upcoming_birthdays.

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

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

The description implies the tool is for viewing upcoming/overdue reminders, but it does not explicitly state when to use it versus alternatives. No exclusions or alternative tool references are provided, which is a clear gap given the sibling list includes reminder_manage for managing reminders.

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