Revamp CRM MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant context: the note is internal and does not notify the contact, and duplicate calls produce duplicate records (concretizing idempotentHint=false). It does not mention auth/permission requirements, but for a non-destructive append this is a solid additive disclosure.

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

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

Three short sentences plus an endpoint, with the critical 'WRITE:' marker and resource scope front-loaded and zero filler. Every clause carries information an agent would otherwise have to infer.

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?

All three required parameters are schema-documented and the description supplies the behavioral gaps an agent needs before writing. The only omission is what the call returns (note id/shape), which matters slightly more here because no output schema exists, but the tool has no side effects on the contact record itself, so the gap is minor.

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

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

Schema description coverage is 100%, with text, entity_id and the entity_type enum all documented in the schema itself. The description only echoes that the note attaches to a contact or deal, which maps to entity_type but adds no format, length, or ID-syntax guidance beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (add) and resource (note) plus the two supported targets (contact or deal timeline), and prefixes with 'WRITE:' so the mutation nature is unmistakable against siblings like revampcrm_get_note or revampcrm_create_deal. An agent can distinguish this from the read-side note tool without opening either schema.

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

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

Clarifies the semantic intent of the resource — an internal note, nothing sent to the contact — which is exactly the distinction an agent needs to choose this over any outward-facing communication. It also warns that calling twice creates two notes, an actionable usage caveat. It stops short of explicitly naming alternatives or when-not-to-use cases, so it lands at 4 rather than 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the count reflects what Revamp CRM has synced (not the store's live totals), a useful nuance, but says nothing about behavior for an unknown provider/store or about rate limits.

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

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

Two short sentences, the purpose is front-loaded, and the endpoint line is supplementary rather than padding. Nothing is wasted.

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

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

With no output schema, the phrase "how many orders" implies a numeric return, which is the minimum an agent needs. It leaves unstated what happens on an unknown store/provider or whether the count is capped, so the description is adequate rather than complete for a two-required-parameter remote API call.

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 both provider and store are already documented in the schema. The description only restates that both are path segments in the GET endpoint, adding no new semantics beyond what the schema provides.

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

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

States a specific verb (count) and resource (e-commerce orders synced for one store), which clearly separates it from the nearest sibling get_order. It does not name any sibling explicitly, so it stops just 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?

"for one store" implies the tool only answers per-store questions, which is a mild scoping constraint an agent can act on. There is no explicit guidance on when to use a count versus get_order or a list call, and no prerequisites or exclusions are given.

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

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

Annotations only declare write/open-world/non-idempotent; the description adds real behavioral facts the annotations cannot express: no email or messaging side effects, no built-in duplicate detection, and the shape of the return payload (status, message, new id in ImportingIntoId) in the absence of an output schema. That is meaningful disclosure beyond the structured fields.

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

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

Front-loaded with a WRITE: marker, then side-effect exclusions, then the dedupe precondition, then return contract and endpoint — every sentence carries distinct information with no 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?

For a 23-param creation tool with no output schema, the description covers the mutation semantics, return values, and duplicate risk, which is the bulk of what an agent needs. It stops short of explaining partial creation, custom-field naming pitfalls, or how a minimal name-only create behaves.

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

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

With 23 parameters and only 48% schema description coverage, the description needs to carry field semantics but says nothing about any of them — no guidance on custom_fields, subscribed enum, required-vs-optional usage, or the ~12 undocumented fields (city, state, gender, phones, emails, addresses). The only implicit hint is "person or organization" tying to name.

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?

States a specific verb and resource ("create a new contact (person or organization)") and scopes it to the Revamp CRM account. It is clearly distinguishable from revampcrm_update_contact and revampcrm_list_contacts without opening either schema, and it names the exact endpoint (POST /Contacts/New).

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?

Gives an explicit precondition and alternative: "Search first (revampcrm_list_contacts with keyword/email) so you do not create a duplicate: this tool does not check." It also excludes an expected-but-absent behavior ("does not email or message the contact"), leaving nothing to inference about when and how to use it.

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

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

Annotations already declare readOnly=false, idempotent=false and openWorld=true; the description adds value by labeling the operation WRITE and explicitly stating no notifications are sent, which is the kind of side-effect scoping annotations cannot express. It doesn't mention duplicate detection or failure behavior, but for a straightforward create that's a minor gap.

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

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

Three short sentences, front-loaded with the WRITE marker and the core action, then dependency pointers. Nothing is wasted and it's scannable at a glance.

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 15 parameters, no output schema, and annotations that don't describe responses, the description never says what a successful create returns (e.g. the new deal id) — an agent would need that to chain follow-up calls like adding notes or marking won. Otherwise the input-side guidance is adequate.

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

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

Schema description coverage is 80%, so the schema already explains nearly every field including deal_stage and currency guidance. The description's pointers to the stage and currency list tools largely duplicate the schema's 'see revampcrm_list_deals_by_stage' note, adding little new parameter meaning beyond the POST /Deals endpoint detail.

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?

States a specific verb and resource ('create a new deal (opportunity)') plus the account scope, and clarifies the optional contact link. It is immediately distinguishable from siblings like revampcrm_update_contact or revampcrm_mark_deal_won.

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

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

Explicitly routes the agent to revampcrm_list_deals_by_stage and revampcrm_list_deal_currencies to resolve required/valid values, which is real use-time guidance. It does not, however, say when to create a deal vs. search for an existing duplicate or how to proceed if the deal already exists.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the breadth of returned details (deal totals, e-commerce order summaries, owner, tasks) and the underlying endpoint, though it does not mention not-found behavior or error handling.

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

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

The description is a single front-loaded sentence that starts with the core purpose before listing details. The field enumeration is long but informative and directly relevant to what the tool returns.

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

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

For a single-record read tool with no output schema, the description is fairly complete: it names the resource, states the key lookup, and enumerates the major return categories. Minor gaps remain around exact response structure and error cases, but the essential context is present.

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

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

Schema coverage is 100%, and the single contact_id parameter is fully documented in the schema with its source (revampcrm_list_contacts). The description adds no further parameter detail, 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 states a specific verb/resource: 'One contact by id with full details.' It clearly distinguishes this from sibling list/search tools by emphasizing retrieval of a single contact by id and enumerating the detailed fields returned.

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 by 'by id' and the schema note that the id comes from revampcrm_list_contacts, so an agent can infer this is for fetching one known contact. However, the description does not explicitly state when to use this instead of list_contacts or other contact-related tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing that the result is scoped to the credentials in use and by naming the concrete backing endpoint (GET /User/WhoAmI). It does not say what happens when credentials are missing or invalid, which would be the remaining behavioral gap.

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

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

Two compact sentences plus the endpoint reference, with the payload fields front-loaded and the cross-tool hint second. Nothing is padded or restated from the title.

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?

There is no output schema, so listing the returned fields in the description is essential and it does so. The binding to owner_user_id / assigned_user_id makes the value of the tool actionable. Slightly incomplete only in that error/unauthenticated behavior and whether the response is wrapped or bare is left unstated.

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 takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-param tool is 4. The description correctly implies the implicit input is the caller's authentication context, which is the only meaningful 'input' here.

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 names the specific resource (the Revamp CRM user bound to the supplied credentials) and enumerates the returned fields (id, name, email, role), so an agent knows exactly what it retrieves. It is a noun phrase rather than a verb+resource construction, but no sibling tool overlaps with 'current authenticated user', so differentiation is implicit 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 only guidance is downstream: 'Use the id as owner_user_id / assigned_user_id', which tells the agent what to do with the result rather than when to call this tool. There is no explicit statement of the trigger condition (e.g. 'call this first to resolve the acting user before creating deals or contacts') and no mention of alternatives or prerequisites such as an authenticated session.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by listing exactly what comes back (text, type, author, related contact and deal, created date) and pinning the underlying endpoint, which is useful since no output schema exists. It omits what happens on an unknown id, which keeps it from a 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?

A single dense sentence plus the endpoint, with the returned-field list front-loaded before the path. No filler, though the sentence is a fragment rather than a complete statement of action.

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 one-parameter read tool with no output schema, the field enumeration compensates well for the missing return documentation and the annotations cover safety. The only shortfall is the absence of any error/not-found behavior for an id that does not exist.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema fully documents note_id including its pattern constraint. The description adds nothing about the id beyond the endpoint path, so the baseline 3 applies.

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

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

The description identifies a single note or timeline entry retrieved by id and enumerates the returned fields (text, type, author, related contact/deal, created date), which makes the resource concrete. It does not explicitly state the verb 'retrieve', relying on 'by id' plus the endpoint path to convey that, and it does not name a sibling, so it stops 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?

Usage is only implied: 'by id' signals that the caller must have a note id in hand, and the alternative to reading is obviously revampcrm_add_note. There is no explicit when-to-use or when-not guidance, and no note that timeline entries are covered by the same call beyond the passing phrase 'or timeline entry'.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds that this is a write to an external provider via a specific HTTP route (GET /Orders/Get/{provider}/{store}/{id}) and that the identifier must be an exact match, which warns about lookup failures. It does not describe behavior when the order or store is not found.

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

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

It is a single dense but well-ordered sentence: the resource first, then the contents, then the prerequisites, then the route. Nothing is redundant, though the parenthetical provider list and endpoint could be trimmed for tightness.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating totals, tax, discount, shipping, statuses, line items, and customer. Missing only edge-case behavior (unknown provider/store or order not found).

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 goes beyond the schema by telling the agent how to obtain valid provider/store values (see the contact's ExternalProviders/Shop) and by clarifying that order_id is the store's own id, not a CRM id.

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?

States a specific verb ('Get'), a specific resource (one synced e-commerce order), and its scope ('by the store's own order id'), plus what the payload contains. It is clearly distinguishable from count_orders and the contact/deal siblings.

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

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

It gives the practical prerequisite for a successful call – provider and store name must match exactly how Revamp CRM stores them, with a pointer to ExternalProviders/Shop on a contact. It does not explicitly rule out alternatives such as count_orders, so it stays just short of 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating the returned fields (name, stage, status, value, currency, closing date, owner), which compensates for the absent output schema, and by naming the underlying REST endpoint.

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

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

Two short sentences, front-loaded with what the tool returns, then the endpoint. Nothing is wasted, though the raw endpoint line is of marginal value to an agent that isn't reasoning about the underlying API.

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

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

With no output schema, the field enumeration is the key completeness contribution, and it is present. Gaps remain around pagination behavior, empty-result handling, and response ordering for a list tool, but for a single-parameter read this is largely 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?

Only one parameter and schema description coverage is 100%, so the schema already documents contact_id fully. The endpoint path 'GET /Contacts/{id}/Deals' weakly confirms the id is a path segment, but the description adds no format or sourcing detail beyond the schema. Baseline 3 applies.

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

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

States a specific resource and scope: 'All deals of one contact.' The contact-scoped framing implicitly separates it from revampcrm_list_deals and revampcrm_list_deals_by_stage, though neither sibling is named explicitly.

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

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

Usage is only implied — an agent should call this when it has a contact id and wants that contact's deals. There is no explicit when-to-use vs when-not guidance, and no mention of when to prefer revampcrm_list_deals or revampcrm_search_deals instead.

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

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

Annotations already cover the read-only/non-destructive profile, and the description adds real value on top: it lists the returned item fields, explains that resultsInfo carries totalCount/hasNext/nextIndex, and specifies passing nextIndex as `page`. It omits rate limits, filter-combination semantics (AND vs OR), and default sort behavior, so not a 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?

Three dense sentences, front-loaded with the core action and default behavior, then return shape, then pagination. Minor waste in the parenthetical '(ContactInfo)' and the vague 'newest filters first' phrase, but overall efficient.

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

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

For a 22-param, zero-required list tool with no output schema, the description covers return contents and pagination adequately. Gaps remain around filter combination logic and default sorting, but the essentials for correct invocation are present.

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

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

Schema description coverage is 68% over 22 parameters, so the baseline is 3. The description only reinforces the `page` paging contract (already in the schema) and lists return fields rather than clarifying filters like subscribed, contact_type, or how sort_by/sort_direction interact, so it adds little per-parameter meaning.

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?

States a specific verb+resource (search/list contacts) with scope ('people and organizations') and the default no-filter behavior, which clearly separates it from get_contact or create_contact. It does not explicitly name a sibling or route between list vs search_deals-style tools, so it stops 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?

It gives one useful usage rule — with no filter it returns all contacts — and explains how to continue paging, but never says when to prefer keyword search over structured filters, when to use this vs get_contact, or any exclusions. Usage is implied rather than guided.

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

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

The annotations already declare readOnlyHint, openWorldHint, and non-destructive behavior. The description adds useful context—account-scoped, ordered stage names and the backing endpoint—though it does not cover authentication, rate limits, or exact response shape.

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

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

Two compact sentences front-load the key information: ordered account-configured stage names and how to use them. The endpoint is a small extra but anchors the operation without adding noise.

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 read-only lookup with no output schema, the description explains the returned values (stage names, in order) and their purpose. It stops short of specifying the exact response type or whether identifiers are included.

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?

There are zero parameters, so the baseline is 4. The description adds no parameter detail because none exist; the mention of contact_stage filters is output usage context rather than parameter semantics.

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

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

The description specifies the resource precisely—contact/lead stage names configured in the account—and notes they are ordered. It is clearly distinguishable from sibling contact and deal tools, though the description itself uses a noun phrase rather than an explicit 'list/returns' verb; the title supplies that verb.

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 says to use the returned names as contact_stage filters and values, giving the primary use case. It does not identify when not to use the tool or which sibling tools accept the contact_stage filter, so it falls short of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds account-wide scope and the returned field set, plus the underlying endpoint, but says nothing about ordering, caching, or behavior if no custom fields exist.

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

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

Two compact sentences front-load the returned attributes and follow with the usage cue; the trailing GET path is the only filler. Nothing is redundant.

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

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

With no output schema, the description must carry the return shape, and it does by naming the four attributes returned including list options. It is sufficient for an agent to call this correctly and interpret the result, with only edge-case behavior left unstated.

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 takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description instead spends that space describing the output attributes, which is the relevant substitute.

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?

States the resource precisely (contact custom fields defined in the account) and enumerates what comes back (CustomFieldName, DisplayName, Type, list options). It clearly differs from get_contact/list_contacts by being the metadata that explains CustomFieldN properties, though the listing verb itself is carried by the name rather than the description.

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

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

"Read this to interpret CustomFieldN values on contacts and to set them" gives an explicit precondition for calling it, which is exactly the right routing hint in this sibling set. It does not name an alternative tool or state exclusions, but no close alternative exists here.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful return-shape context (name, value, symbol) and the underlying endpoint, but says nothing about whether the set is account-configured, static, or whether the list can be empty.

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

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

Two short sentences with the resource and return fields front-loaded; nothing is padded. The trailing raw endpoint ('GET /Account/DealCurrencies') is arguably noise for an agent that cannot issue raw HTTP calls, but it costs little.

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, read-only lookup with no output schema and full annotation coverage, the description supplies the essential facts: what the list contains and what each entry looks like. Only minor gaps remain (whether results depend on account settings, ordering, or caching).

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 takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The enumerated return fields are the only semantic content it could add, and it does so briefly.

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?

Names the specific resource (currencies that deals in this account can use) and enumerates the returned fields, so an agent can tell it apart from sibling deal tools like list_deals or get_order. The verb is only implied ('The currencies that...'), a fragment rather than a stated 'List', which keeps it just 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?

There are no competing siblings for currency data, so the absence of explicit 'when to use' is less costly, but the description never states a trigger such as 'call this to discover valid currency values before create_deal'. Usage is only implied by the resource 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?

Annotations already cover read-only and open-world safety. The description adds genuinely useful behavior beyond that: no paging, the reply is truncated to `limit`, and it reports how many matched. It does not mention auth or rate limits, but the truncation disclosure is valuable.

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

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

Three sentences, front-loaded with purpose, then return shape, then truncation note. No wasted text.

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

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

Given no output schema, the description usefully names the fields each deal contains and explains the truncation/count behavior. It omits sorting semantics and error behavior, but an agent has enough to call 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?

Schema description coverage is 93%, so the schema already explains nearly all 14 parameters in detail. The description only groups the filter categories and lists returned deal fields, adding little parameter-specific meaning beyond the structured schema.

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

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

Clearly states the verb and resource ('List deals') and specifies scope via optional filters and returned fields. It does not distinguish itself from closely named siblings like revampcrm_search_deals or revampcrm_list_deals_by_stage, but the core purpose is unambiguous.

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

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

The description implies this is the general listing tool with optional filters, but it never says when to choose it over search_deals, list_deals_by_stage, or list_contact_deals. An agent must infer the routing.

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

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

Annotations already declare a safe read (readOnlyHint true, destructiveHint false), so the description only needs to add shape. It does: results are bucketed by stage, stage labels come back in CurrentStages, the limit applies per stage rather than overall, and it discloses the underlying GET /Deals/ByStage call. It stops short of describing ordering of stages or truncation behavior.

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

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

Three short sentences, front-loaded with what the tool returns, then the limit semantics, then the endpoint. No filler and nothing buried.

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 14-parameter tool with no output schema, the description gives only a hint about the response (a CurrentStages list) without explaining the grouping structure, whether empty stages appear, or how sorting applies within groups. Enough to call it, not enough to use the result confidently.

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 93%, so the schema does nearly all the work, and the description's one parameter claim (limit is per stage) restates the limit property's own description. It adds no format, default, or interaction detail for the other 13 filters beyond pointing at revampcrm_list_deals.

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 names the specific resource and view: deals grouped by stage, i.e. the pipeline board, and states that stage names appear in CurrentStages. That distinguishes it cleanly from revampcrm_list_deals and revampcrm_search_deals without opening either schema.

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

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

"Same filters as revampcrm_list_deals" gives useful context and implicitly routes the agent, but it never states when to pick this over the flat list tool or search_deals, nor any exclusions. The choice between the grouped and ungrouped views is left to inference.

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?

Beyond the 'destructive' annotation, the description provides critical constraints: 'It does not message the contact,' which is a specific behavioral limitation. It also explains the operational consequence of the change ('it counts in lost-deal reports').

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 efficient, packing the operational consequence, behavioral constraints, prerequisite usage, and technical details (POST path) into a concise, well-structured text block.

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 lacking an output schema, the description covers all necessary contextual information, including the change to deal status and its impact on reporting. The constraints are clearly defined, making the definition complete for agent execution.

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?

Since the schema coverage is 100%, the structured data already fully defines the parameters (deal_id, reason, note). The description primarily reinforces the purpose of the inputs rather than adding new semantic meaning.

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

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

The description clearly states the action ('mark a deal as Lost') and the resource ('deal in Revamp CRM'). It is highly specific and immediately distinguishes itself from sibling tools like revampcrm_mark_deal_won.

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 provides explicit guidance on prerequisite usage by advising the agent to 'Check the deal first with revampcrm_search_deals.' This sets a clear operational flow before invoking the 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?

Annotations already flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds real value beyond them: the downstream reporting effect and, critically, that no contact notification is triggered. It omits reversibility (whether mark_deal_lost or a stage change can undo it) and any permission requirements for a destructive write.

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?

Front-loaded with the 'WRITE:' danger marker, then effect, then exclusions, then prerequisite — good ordering with no filler. The trailing 'POST /Deals/Won' is transport detail that adds little for an agent choosing a tool, the only wasted token.

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 destructive mutation with full schema coverage and no output schema, the description covers effect, side effects (no contact message) and pre-flight verification. The main residue is that it never says what the call returns on success, which matters slightly since no output schema exists.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents both deal_id and the optional note. The description adds nothing about either — notably never mentioning that a note is accepted — so it neither compensates nor does harm; baseline 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?

States a specific verb and resource ('mark a deal as Won in Revamp CRM') plus the concrete consequence ('its status changes and it counts in won-deal reports'). The Won framing cleanly separates it from the sibling revampcrm_mark_deal_lost without needing to name it.

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?

Gives an explicit prerequisite ('Check the deal first with revampcrm_search_deals') and an explicit scope exclusion ('It does not message the contact'). It stops short of any when-not guidance, e.g. what to do if the deal is already won or already lost.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), but the description adds genuinely new behavior: Revamp CRM applies the limit server-side, no total is returned, and may_have_more signals a full page. That is exactly the kind of pagination caveat an agent needs. It does, however, conflict with the schema's claim that 'the reply says how many matched in total', creating uncertainty about the return contract.

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

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

Three tight sentences: filterable fields first, then the pagination caveat, then the endpoint. Every sentence carries information, though the trailing 'GET /Deals/Search' is low-value for an agent that never makes raw HTTP calls.

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 14-parameter tool with no output schema, the description does the important work of explaining the result envelope (no total, may_have_more) and the text-match nature of filters. The contradiction about total counts and the unmentioned sorting/date/value parameters leave minor gaps, but nothing critical is missing for correct 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?

With 50% schema coverage across 14 parameters, the description compensates partially by naming most filter fields and noting they are text matches. It omits sort_by, sort_direction, value, and expected_close_date entirely, and its statement about limit semantics directly contradicts the limit parameter's own schema description, so it does not fully resolve the gaps.

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?

States a specific verb ('Search') and resource ('deals') and enumerates nine filterable fields, giving a precise picture of what can be queried. It does not distinguish itself from siblings like revampcrm_list_deals or revampcrm_list_deals_by_stage, so an agent must infer which list-style tool to pick.

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 mention of text matching 'as Revamp CRM defines it' hints at when this is appropriate (fuzzy/any-field lookup) versus exact listing, but there is no explicit when-to-use, when-not-to-use, or named alternative among the three deal-listing siblings.

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

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

Goes well beyond the annotations by disclosing the read-modify-write mechanics, the fact that the CRM replaces the whole record while only passed fields change, that tags replaces rather than appends, and that no message is sent – exactly the context destructiveHint/idempotentHint cannot convey. It stops short of describing error behavior (e.g., invalid contact_id) or response shape.

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?

Five short sentences, zero padding: mode marker first, then partial-update semantics, then the tags caveat, then the non-effect, then the endpoint. Every sentence carries distinct 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 24-parameter destructive mutation with no output schema, the description covers the risky parts (overwrite semantics, tags replacement, no messaging) and the underlying PUT path. Gaps remain around failure modes and what comes back, which is acceptable given no output schema but still a small hole for a destructive 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?

With 24 parameters and only 50% schema coverage, the description compensates by explaining the global update semantics ('only the fields you pass change', 'passing a field overwrites its old value') and the special replace behavior of tags. It does not touch the many undocumented per-field params, but the schema covers patterns/enums and custom_fields.

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?

States a specific verb ('change fields') plus scope ('existing contact') and front-loads 'WRITE:', which cleanly separates it from revampcrm_create_contact and revampcrm_get_contact without needing the schema.

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

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

Makes clear this applies to an existing contact only and rules out a side effect ('does not email or message the contact'), but never explicitly names the sibling to use for creation or reading, so the agent must infer the routing.

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