noCRM.io MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, yet the description adds genuinely new context: the comment is visible to the lead's team but sends nothing to the customer, and it names the underlying POST endpoint. "Not idempotent" merely restates the annotation, which keeps it short of 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 tight sentences with the "WRITE:" marker front-loaded so an agent knows the mutation class immediately. No sentence is filler; each adds audience, optionality, or idempotency 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 3-parameter write tool with no output schema, the description covers what is created, who can see it, optional typing and non-idempotency. It stops short of saying what the call returns (e.g., the created comment id), which would matter for follow-up calls.

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 lead_id, content (1–20000 chars) and activity_id with a pointer to nocrm_list_activities. The description only echoes that activity typing is optional and never explains the valid activity_id source or content formatting beyond the schema, 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?

States a specific verb and resource ("add a comment ... to a lead") and clarifies the nature of the resource ("an internal note"), which cleanly separates it from the sibling nocrm_list_lead_comments by verb. The optional activity-typing is also disclosed up front.

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 reach for it (posting an internal note the team should see, possibly typed as a call or meeting), but it never explicitly contrasts with nocrm_list_lead_comments or other lead-mutation siblings like nocrm_update_lead. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the 'WRITE:' prefix largely restates what the agent already knows. The description adds nothing about what 'destructive' means here (does the lead leave unassigned/other folders?), failure modes, or permissions required.

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 WRITE marker front-loaded; nothing is wasted. The raw endpoint path is of marginal value to an agent but 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?

This is a destructive, open-world mutation with no output schema, and the description says nothing about side effects, whether the lead is moved versus copied, or what happens on repeat calls despite the idempotent hint. For a write tool it leaves meaningful behavioral questions unanswered.

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 both required parameters are documented, including a pointer to nocrm_list_client_folders for client_id. The description adds no semantics beyond the schema, 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?

'WRITE: file a lead under a client folder' gives a specific verb and resource, and the endpoint path confirms the operation. It doesn't explicitly contrast with siblings like nocrm_assign_lead or nocrm_add_lead_comment, but the action is unambiguous without opening 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?

There is no statement of when to use this versus alternatives such as nocrm_assign_lead or nocrm_update_lead, nor any prerequisite or exclusion. The only routing hint (client_id 'see nocrm_list_client_folders') lives in the schema, not the description.

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

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

Goes beyond the annotations by explaining the destructive impact ('replacing its current owner') and disclosing a side effect the annotations cannot express: the new owner may receive a noCRM.io notification. It does not cover what the prior owner retains or what permissions are required, so it stops short of full transparency.

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

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

Three short sentences with the write nature and resource front-loaded, then the key behavioral caveat, then the endpoint. Nothing redundant or padded.

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 mutation with no output schema and annotations already declaring destructive/idempotent/write semantics, this covers the essential behavior plus the notification side effect. Only minor gaps remain, such as the response shape and failure cases.

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

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

Schema description coverage is 100%, so both parameters are already documented. The mention of '(id or email)' for user_id merely restates what the schema's anyOf already conveys, so the description adds no new 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 and resource ('assign a lead to a user') and clarifies scope by saying it replaces the current owner, which distinguishes it from nocrm_update_lead and complements nocrm_list_unassigned_leads. The 'WRITE:' prefix and endpoint make the operation unmistakable, though no 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 implied by the operation itself: use it to move ownership of a lead. However, there is no explicit guidance on when to prefer nocrm_update_lead instead, or any prerequisite such as needing an existing user id.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so 'WRITE: ... Not idempotent' is largely restatement. Beyond that it only adds the HTTP endpoint, with no detail on permissions, duplicate-name behavior, or what is returned — the kind of context a create tool would benefit from.

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 terse, front-loaded fragments — operation type, entity definition, behavioral caveat, endpoint. Nothing extraneous and the critical noun phrase comes first.

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

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

For a create tool with no output schema, the description does not say what the caller gets back (presumably a new folder id) or whether the folder is immediately usable by nocrm_add_lead_to_client_folder. Annotations and the full schema cover most of the surface, but that return-value gap remains.

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 every parameter (name, user_id, description) is documented inline with constraints. The description adds no parameter-level meaning beyond the schema, which is acceptable at 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?

Specific verb+resource ('create a client folder') with a parenthetical that defines the domain concept ('an account that groups leads'), which cleanly separates it from nocrm_create_lead and nocrm_add_lead_to_client_folder. The endpoint reference (POST /clients) reinforces the resource.

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 'WRITE:' prefix and the entity definition imply this is the tool for creating a new client folder rather than attaching to an existing one (nocrm_add_lead_to_client_folder). However, there is no explicit when-to-use/when-not guidance or named alternative, 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.

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

Annotations already declare readOnlyHint=false and idempotentHint=false, yet the description adds real substance: the POST /leads endpoint, the assignment dependency that gates step, and the parsing contract that the server reads the free-text description line by line. These are non-obvious side effects and preconditions not derivable from the annotations.

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

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

Four short clauses, front-loaded with the write semantics, then the description format, then the assignment rule, then the idempotency warning. No filler and nothing buried at the end that changes the decision to call.

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 5-parameter creation tool with rich annotations, the description covers the mutation, the parsing format, and the assignment precondition. The remaining gap is the return value — with no output schema, nothing states whether the new lead's id comes back, which an agent needs to chain into follow-up calls.

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, but the description earns above that by explaining the cross-parameter dependency (step requires user_id; no user_id means unassigned) and by specifying the 'Label: value' line syntax for description. It doesn't touch tags or title beyond what the schema states.

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?

Opens with an explicit verb+resource ('WRITE: create a new lead') and a typed prefix that separates it from read siblings like nocrm_get_lead and from the mutation sibling nocrm_update_lead. An agent can route on this line alone without opening 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?

Gives concrete usage conditions: omit user_id to create unassigned, and step is only valid when the lead is assigned. It also warns 'calling twice creates two leads', which signals a dedupe check before calling. It never names an alternative tool (e.g. nocrm_update_lead for existing leads, nocrm_get_lead_duplicates for pre-checks), so it stops short of full when/when-not 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 readOnlyHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds that the response includes contact fields and owner, but it does not mention error behavior, permissions, or other operational details. This is useful but modest beyond annotations.

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

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

The description is two short sentences, front-loading the resource and scope before the endpoint. Every clause carries useful 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 simple single-parameter read tool with complete annotations and schema coverage, the description is nearly complete: it states the resource, required identifier, and returned content. Minor gaps such as not-found behavior or permission requirements keep it from a 5.

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

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

Schema coverage is 100%, with client_id fully documented as "Client folder id." The description's "by id" adds no syntax or constraints beyond the schema, so the baseline 3 is appropriate for a single well-documented parameter.

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 gives a specific verb/resource ("One client folder by id") and names the returned content (contact fields and owner), distinguishing it from list_client_folders by its singular, id-based scope. It does not explicitly name sibling alternatives, but the purpose is clear.

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

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

Usage is implied by "by id" and the endpoint reference: call it when you already have a client folder id and need that folder's details. There is no explicit when-not guidance or named alternative such as list_client_folders.

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 by enumerating the returned fields (including the full description and contact details), which is important since no output schema exists. It stops short of describing error behavior for invalid or missing ids.

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: the resource and scope are front-loaded, followed by the returned fields and the underlying endpoint. Every part earns its place 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?

With no output schema, the description appropriately enumerates the returned fields, making the response shape predictable. For a simple single-record read with one required parameter, this is nearly complete; only edge-case behavior (e.g., not-found handling) is absent.

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

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

Schema description coverage is 100%, and the single lead_id parameter is documented in the schema ('noCRM.io lead id'). The description only restates 'by id' and adds no format, range, or lookup guidance beyond what the schema provides, so 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 verb and resource ('One lead by id') and enumerates what is returned (title, step, status, tags, owner, etc.). This clearly distinguishes it from sibling list tools like nocrm_list_leads and mutation tools like nocrm_update_lead.

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: fetch a single lead by its id. However, there is no explicit statement of when to use this versus nocrm_list_leads or nocrm_get_lead_duplicates, and no prerequisites or exclusion conditions 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing how duplication is determined (same email or key field) and that detection is performed by noCRM's own matching logic rather than a caller-supplied query. It stops short of describing the return shape or result count.

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, both front-loaded with the resource definition before the endpoint reference. Nothing is redundant and nothing is padding.

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-parameter read tool with full annotation coverage and full schema coverage, the description supplies everything needed to call it correctly. The only gap is what the response looks like (a list of lead records?), which matters slightly more because there is no output schema.

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

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

Only one parameter exists and schema coverage is 100%, with the schema documenting lead_id as the noCRM.io lead id. The description's '{id}'/'this lead' wording restates the same meaning without adding format or constraint detail, 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 states a specific resource and scope — leads that noCRM.io considers possible duplicates of the given lead — and even defines the duplicate criteria (same email or key field). It is easily distinguished from nocrm_get_lead and nocrm_list_leads, though it does not name those siblings 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 can infer this is a pre-create check or a dedupe lookup, but the description never says when to call it versus fetching the lead or listing leads. No exclusions or prerequisites are stated.

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 clear. The description adds the endpoint and identifier flexibility but does not describe return format, error behavior (e.g., user not found), or other operational traits beyond the annotations.

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

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

Two short sentences, front-loaded with the core action and followed by the endpoint. Every sentence earns its place with no redundancy.

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

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

For a simple read-only lookup with a fully described single parameter and clear safety annotations, the description is nearly complete. It could mention return shape or not-found behavior, but the absence of an output schema makes that less critical.

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 parameter's meaning (user id or email address) is fully documented in the schema. The description echoes this but adds no additional syntax or format guidance 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 states a specific retrieval action for a single user, identifying by id or email address and providing the underlying endpoint. It distinguishes implicitly from the sibling nocrm_list_users (one user vs. a list), but does not explicitly name or contrast with that sibling.

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 'One user by id or email address' clearly indicates when to use this tool, and the schema parameter description points to nocrm_list_users as an alternative for listing. However, the description itself offers no explicit when-not or alternative tool naming.

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 these values attach to comments/reminders, which is useful context, but it discloses nothing about the return shape or ordering. The trailing 'GET /activities' is developer-facing noise rather than behavioral disclosure.

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

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

Two short sentences, front-loaded with the substance. The trailing REST endpoint path is the only wasted token and does not help an agent decide or invoke.

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 burden of describing return values, and it does so by naming the members of the returned set. For a zero-parameter read-only reference lookup, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming that no filtering is possible. Baseline 4 applies.

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

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

The description names the resource precisely ('activity types') and enumerates its members (call, email, meeting and outcomes), which separates it from reference-data siblings like nocrm_list_pipelines or nocrm_list_predefined_tags. It is a noun phrase rather than a verb+resource construction, but the intent 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?

It states the types 'can be set on a comment or reminder', which implies the use case (resolving valid values before adding a comment or follow-up) but never explicitly says when to call it or what to do instead. No exclusions or prerequisites 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the default ordering and the underlying endpoint, but says nothing about pagination, result limits, or whether the full set is returned — notable gaps for a list operation.

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

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

Two compact fragments, front-loaded with the resource definition, and no filler. The endpoint reference is marginal value but costs almost nothing.

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

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

With no output schema, the description should clarify what a returned folder contains and whether results are paginated or truncated. It leaves both unstated, so an agent can call the tool but cannot predict the response shape.

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 both parameters are enum-constrained with their own descriptions, so the schema does the work. The description only reinforces the "name by default" behavior already present in the schema; it adds no syntax or edge-case 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?

The description names the resource and defines it in domain terms ("accounts that group several leads"), which lets an agent distinguish it from nocrm_get_client_folder or nocrm_list_leads. The verb is carried by the title rather than the description, but the intent 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?

There is no statement of when to use this versus nocrm_get_client_folder (single folder) or how it relates to nocrm_list_leads. No prerequisites or exclusion conditions are given; an agent must infer that this tool retrieves all folders.

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 safety is covered. The description adds only the raw endpoint path 'GET /fields' and says nothing about what a lead-vs-client field set contains or whether results are paginated.

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?

Very short — two fragments — so nothing is bloated, but it is under-specified rather than concise. The 'GET /fields' endpoint string consumes half the text without informing tool selection.

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 the description should convey what a returned field definition looks like (ids, names, types) and how the two field sets differ. Neither is present, leaving the agent unable to anticipate the response for a tool it must otherwise guess about.

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

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

Schema description coverage is 100% and the single 'type' parameter is already documented with its enum, so the baseline is 3. The phrase 'for leads or client folders' loosely echoes the enum values but adds no format or default behavior detail 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?

Names the resource (custom fields) and its scope (leads or client folders), so an agent can infer this is a read of field definitions. However, the sentence is a noun phrase with no verb, and nothing distinguishes it from sibling list tools such as nocrm_list_predefined_tags or nocrm_list_pipelines beyond the resource name.

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

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

No indication of when to call this versus the many other list_* siblings, no prerequisites, and no note on whether the type filter is required or what omitting it returns. The agent must infer all call conditions.

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

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

Annotations already carry the safety profile (readOnly, non-destructive, openWorld), so the description's added value is the edition gating that produces an HTTP 403 and the underlying endpoint. Those are real behavioral facts an agent cannot get from structured fields. It stops short of describing pagination or volume characteristics, 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?

Three short sentences: resource definition, parameter prerequisite, then the edition/error caveat with the endpoint. No filler, and the scope constraint is front-loaded.

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

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

For a three-parameter read-only list with full schema descriptions and annotations present, the description supplies the two facts structured data omits (OR-scoping requirement, edition gating). It does not cover what happens if both IDs are passed or how results are ordered/limited, which is a minor remaining gap.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds something the schema does not encode: the schema lists no required fields and no oneOf constraint, while the description states that one of lead_id or user_id must be supplied. That squarely compensates for the missing required-parameter signal.

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 defines the resource precisely — post-sales task checklists generated from a template, scoped to one lead or one user — which is more informative than the title alone. It lacks an explicit verb, but the 'GET /follow_ups' trailer and the 'of one lead OR of one user' scope make the operation unambiguous and clearly distinct from sibling list tools (activities, leads, comments).

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?

'Needs lead_id or user_id' gives the caller the concrete precondition for a successful call, and the HTTP 403 note warns ahead of time that the call will fail on non-higher-edition accounts. There is no explicit when-not guidance, but no sibling tool overlaps this resource, so there is little alternative to disambiguate against.

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 by naming the shape of the result (names, ids, sizes, links), but says nothing about pagination, ordering, empty results, or auth requirements.

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

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

Two compact fragments that front-load the resource and result fields with zero filler. The endpoint restatement is slightly redundant given the tool name but does no harm.

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-parameter read tool with full schema coverage and annotations, this is nearly complete, especially since it delineates the return fields in the absence of an output schema. Missing pagination/result-count information keeps it from a 5.

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 (lead_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax or format details about lead_id beyond what the schema already provides, making the baseline 3 appropriate.

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

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

Names the specific resource (file attachments on a lead), enumerates the returned fields, and cites the exact endpoint GET /leads/{id}/attachments. This clearly distinguishes it from sibling list tools such as nocrm_list_lead_comments and nocrm_list_lead_history.

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 infers it should call this when it needs a lead's attachments. There is no explicit statement of when to prefer it over nocrm_get_lead or other lead-detail tools, 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the default sort order ('newest first'), which is already conveyed by the direction parameter's schema description, and says nothing about result volume or pagination.

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 essential content front-loaded; nothing is wasted and it is easily scanned. The trailing raw endpoint path adds little for an agent but is harmless.

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 read listing with full schema coverage, no output schema, and annotations covering safety, the description provides enough to call the tool correctly. The only notable gap is whether results are truncated or paginated.

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 parameters (lead_id and direction enum) are fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond what the schema already provides, so 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?

Clear specific verb+resource: lists comments on a lead, and clarifies that 'comments' encompasses notes, logged calls/meetings/emails, which removes ambiguity about returned content types. It implicitly contrasts with nocrm_add_lead_comment but never names or routes between siblings 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 implied by the read-only listing framing and the required lead_id, but there is no explicit statement of when to choose this over nocrm_list_lead_history, nocrm_list_activities, or nocrm_get_lead. No exclusions or prerequisites 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value by describing the timeline contents and who/when attribution, but says nothing about pagination behavior, result volume, or permissions.

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

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

Two compact sentences: content inventory first, filter options second, endpoint last. No filler and every clause carries 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?

No output schema exists, but the description enumerates the returned event kinds and includes actor and timestamp, which is enough for an agent to know what comes back. Only pagination and result-size expectations are left implicit.

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%, including detailed enum values and pagination semantics (next_offset), so the baseline is 3. The description's 'filter by ... user' is slightly misleading because no user filter parameter exists in the schema.

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

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

States a specific verb (List) and resource (lead history timeline) and enumerates the event types covered: creation, assignments, step/status changes, amount changes, comments, emails. This distinguishes it from nocrm_list_lead_comments and nocrm_list_activities 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?

Says what can be filtered (date range, action type, user) which implies when to reach for it, but never states when to prefer nocrm_list_lead_comments or nocrm_list_activities instead, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior: default sort, the default exclusion of unassigned leads, and the set of fields returned in the result — useful context an agent would otherwise have to infer. Minor tension between 'newest first by default' and the schema's stated order default of 'id'.

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 with no filler: scope first, then filters, then the default-exclusion caveat. Every clause carries information an agent needs.

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 15-parameter tool with no output schema, the description usefully lists returned fields and notes the unassigned default, but leaves pagination behavior (limit/offset/next_offset) to the schema. That is acceptable given full schema coverage, though one more sentence on paging would make it complete.

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

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

Schema description coverage is 100%, so all 15 parameters are already documented, and the description's parameter guidance ('names or ids, not mixed', filter list) largely restates the schema. The 'GET /leads' endpoint note and the unassigned-exclusion default add some value but not much beyond structured fields. 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?

States a specific verb and resource ('List or search sales leads'), clarifies the noCRM.io domain term (opportunities), and enumerates the fields returned. This distinguishes it clearly from nocrm_get_lead (single lead) and nocrm_list_unassigned_leads (unassigned scope).

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

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

The description lists every filter dimension (status, step, owner, tags, email, starred, date range) and states that unassigned leads are excluded unless include_unassigned is true, which implicitly routes the agent to nocrm_list_unassigned_leads. It stops short of explicitly naming sibling alternatives such as nocrm_get_lead for single-record lookups.

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 genuinely useful behavior context — that the result is typically a single pipeline unless the multiple-pipelines feature is enabled — but says nothing about the shape or size of returned data, and the HTTP path is only marginally informative.

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 clauses with the core fact (the pipelines of the account) front-loaded and no filler. The trailing 'GET /pipelines' is the only arguably expendable element, since the annotations already convey that this is a read.

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 zero-argument list tool the description covers what is returned at a high level, and the cardinality note is a real aid. However, with no output schema defined, an agent gets no hint about the fields a pipeline object contains (e.g. id, name, steps), leaving a meaningful gap.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter detail is missing or misleading.

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 exact resource (sales pipelines of the account) and the parenthetical clarifies cardinality, so an agent knows precisely what it retrieves. It lacks an explicit verb, relying on the title 'List pipelines' to convey retrieval, but the resource is unambiguous and distinct from all siblings (leads, steps, teams, users).

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 statement of when to call this versus anything else, and no prerequisites or preconditions are given. Because no sibling tool covers pipelines, the risk of misselection is low, but the description offers no positive guidance about context of use.

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

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

With readOnlyHint and openWorldHint already provided, the description adds genuinely useful behavioral context beyond annotations: the admin-key authorization requirement and the specific 401 failure semantics. It does not cover pagination, ordering, or what the tag payload contains, so it is strong 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 short and front-loads the resource and the key authorization caveat. The trailing 'GET /predefined_tags' is slightly redundant with the tool name but still useful as a precise endpoint reference, so little 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?

For a no-parameter list tool with no output schema, the description covers authorization and failure semantics but does not say what the returned predefined tags look like or whether the list is paginated. The agent knows how to call it safely but not what to expect back.

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 there is no parameter semantics to explain; the baseline for 0 params is 4. The description appropriately does not invent 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 identifies the specific resource (predefined tags belonging to the account) and the HTTP method via the endpoint, making its purpose clear relative to other list_* siblings like list_fields or list_steps. It stops short of an explicit verb phrase such as 'Lists all predefined tags', but the resource scope 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?

It gives a real usage constraint ('admin keys only') and explains what an HTTP 401 unauthorized_non_admin means, which helps an agent decide whether it can call it. However, it offers no guidance on when to prefer this tool over related listing tools such as list_fields, leaving alternative selection implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful detail beyond that — the returned fields (ids, positions, pipeline) and the GET /steps endpoint — but is silent on whether results span all pipelines or one, and on pagination or result size.

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

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

Two short sentences plus the endpoint, with the payload contents and the practical use front-loaded. Nothing is padded, though the bare 'GET /steps' adds little for an agent.

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 and only one optional parameter, the description does the right thing by enumerating the returned fields. However, given the ambiguous scope (all pipelines vs. a specific one) and the presence of nocrm_list_pipelines as a sibling, the description leaves the agent to guess its relationship to pipelines.

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 single optional 'direction' enum parameter has 100% schema description coverage, so the baseline is 3. The description never mentions the direction control and its 'in order' phrasing could even mislead an agent into assuming ascending order is the only option.

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?

Specific verb+resource: 'The steps (stages) of the sales pipeline in order, with ids, positions and their pipeline' tells the agent exactly what is returned and that it is ordered. It stops short of distinguishing itself from the nearest sibling, nocrm_list_pipelines, which is not named anywhere.

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?

'Use the ids or names when filtering leads or moving a lead' explains what the output feeds into, which implies when the tool matters, but there is no explicit when-to-call guidance and no mention of when to use nocrm_list_pipelines instead (e.g. to discover pipeline ids first).

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 safety is covered. The description adds genuine context beyond that: the feature-flag prerequisite and the concrete failure mode (HTTP 403), plus a hint at the response payload shape. Pagination or result-size behavior is not disclosed, keeping it short of 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 short sentences, front-loaded with what is returned, then the prerequisite and the failure mode. The trailing 'GET /teams' endpoint notation is mildly redundant with the tool name but is compact and harmless.

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 the description carries the burden of describing returns — it does so at a summary level (teams, members, managers). Combined with the disclosed prerequisite and error behavior, an agent has enough to call it correctly; only pagination/vollume details are absent.

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. Nothing in the description is needed to explain inputs, and it correctly implies an unfiltered full listing.

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 resource and its payload concretely: sales teams, their members, and who manages each — an agent immediately knows this is the 'list teams' read. It doesn't name a sibling or contrast with nocrm_list_users, but the resource is distinct enough from the other list_* tools that confusion is unlikely.

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: the tool lists teams, so use it when team data is needed. The one real guideline given is the account prerequisite (Teams feature enabled, otherwise HTTP 403), which is a useful pre-condition but not a when-to-use-vs-alternative rule. No mention of when to prefer nocrm_list_users 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds a useful semantic definition of what 'unassigned' means, but says nothing about pagination behavior, result ordering, or the shape of returned records.

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, no filler, with the defining concept front-loaded and the endpoint appended. Every element earns its place.

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

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

For a single-parameter read endpoint with annotations and no output schema, the description covers what matters for correct invocation. Only the absence of any hint about the returned list's contents keeps it short of 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?

There is one optional parameter with 100% schema description coverage ('Results per call, 1-100 (default 25)'), so the schema fully carries parameter meaning. The description adds nothing beyond it, which is the baseline for full 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?

States a specific resource plus a precise qualifier ('leads that have no owner yet'), which implicitly distinguishes it from nocrm_list_leads. It never names that sibling explicitly, so the differentiation is inferable rather than stated.

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 examples of web-form and API leads imply when this list is useful, but there is no explicit guidance such as 'use nocrm_list_leads when you want all leads' or 'follow with nocrm_assign_lead to hand off'. Usage is implied only.

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 genuinely non-obvious behavior: deleted users are still returned and are flagged with is_disabled. That is meaningful context beyond the structured fields, though it omits pagination or result-size 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?

Two compact sentences with the resource and the returned fields front-loaded and the endpoint appended as a locator. No filler, though the field enumeration is dense and slightly awkward 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?

With no output schema, describing the returned fields is valuable and mostly done. However, for a 6-parameter listing tool with only 67% schema coverage, the description should at least hint at the available filters and result-set scope, which it does not.

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 67%, so the baseline is 3. The description clarifies the semantics of role ('admin or not') and status ('active or deactivated') and ties them to the is_disabled flag, but says nothing about the email, teams, firstname, or lastname filters that make up the remaining parameters.

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

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

The description names the resource (users/salespeople of the account) and enumerates the returned fields, and the trailing 'GET /users' anchors it to a concrete endpoint. It does not explicitly contrast with the sibling nocrm_get_user (single-user fetch), but the list-vs-get distinction is inferable from the name and result-set wording.

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 statement of when to use this tool versus alternatives like nocrm_get_user, and no mention of the available filtering dimensions (email, teams, name). The agent gets no routing guidance beyond the tool 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious semantics beyond that: tags replaces the entire tag list, description text is append-only and never overwritten, and only supplied fields mutate. It stops short of stating irreversibility of status changes or any side effects of moving to won/lost.

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 label and the object being mutated, then the field list, then the caveats. It is dense but each clause carries information; the enumeration of status enum values and the field list duplicate schema content, which is the only 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 13-parameter mutation with no output schema, the description covers the mutation model (partial update), the destructive replace semantics for tags, the append-only semantics for description, and the conditional remind_date requirement. With annotations carrying the safety profile, nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 85%, so the schema already documents step, tags, amount, status, remind_date, remind_time, append_description and estimated_closing_date. The description's field list largely restates that content (including the status enum values and the standby/remind_date dependency), with only the partial-update rule adding meaning not already in the schema.

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

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

Opens with an explicit verb classification ("WRITE: change a lead") and enumerates exactly which attributes are mutable, ending with the underlying endpoint PUT /leads/{id}. An agent can immediately distinguish this from nocrm_create_lead or nocrm_assign_lead without opening 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?

Gives clear operating conditions: "Only the fields you pass change" establishes PATCH-like partial-update behavior, and "Moving to standby needs remind_date" states a conditional prerequisite. It does not, however, route the agent to siblings for adjacent tasks (assignment, comments, tags listing), so there is no explicit when-not guidance.

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