Vtiger MCP by usefulapi

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds genuinely new context beyond them: 'existing tags stay' clarifies merge behavior, POST /tags_add names the endpoint, and 'Not retried' discloses retry policy. This is useful supplementary context, though it doesn't cover failure modes or 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?

A single compact sentence-plus-tags with the operation type front-loaded and zero filler. Every clause (write, one record, merge semantics, endpoint, retry) 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 simple two-parameter mutation with full schema coverage and annotations covering safety and idempotency, the description supplies the key behavioral facts (merge semantics, endpoint, retry policy). No output schema exists, so return values go unexplained, but that is a minor gap for a tagging operation.

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

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

Schema coverage is 100%, so both parameters (id with its moduleTypeId format, tags with item constraints) are fully documented in the schema. The description adds no parameter detail beyond repeating 'one record', 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 ('add tags to one record') with the scope qualifier 'one record' and the merge semantics '(existing tags stay)', which clearly separates it from the read-side sibling vtiger_get_tags. The 'WRITE:' prefix immediately signals the operation class.

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:' marker and 'Not retried' note imply this is a mutating call that shouldn't be auto-retried, but there is no explicit when-to-use/when-not guidance or named alternative such as vtiger_get_tags for reading tags. 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?

readOnlyHint=true already establishes the safe-read profile, and the description adds useful context by naming the underlying aggregation (GET /query with count(*)), confirming it is a server-side count rather than a fetch-and-tally. It says nothing about limits on filter combinations beyond the schema's maxItems or about the response value being a plain 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 clauses with the purpose front-loaded and zero padding; the endpoint detail is compact and contributes transparency rather than noise. Nothing in it is wasted, though it is terse to the point of under-specifying usage.

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 read-only count tool with full schema coverage, no output schema, and a readOnlyHint annotation, the description covers what the tool does and how filters relate to the sibling tool. The only real gap is that it doesn't state that the return value is a simple integer count, which an agent could otherwise assume wrongly.

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 documents module names, the operator enum, AND combination, and the maxItems cap, so the schema carries the semantic load. The description's only added value is cross-referencing the filter syntax to vtiger_list_records, which is helpful but marginal.

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 operation (count records of a module) and explicitly ties its filter semantics to the sibling vtiger_list_records, so an agent can tell it apart from the listing tool. The phrasing is slightly indirect ('How many records...') but still unambiguous about the verb and resource.

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

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

The reference to 'same filters as vtiger_list_records' implies this is the counting counterpart to listing, but the description never says explicitly when to use it over vtiger_list_records (e.g. 'use when you only need a count, not the rows'). 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 only declare destructiveHint=false; the description adds crucial behavior: this is a WRITE, returns the new record, uses POST /create, and is 'Not retried' — a meaningful idempotency warning that prevents duplicate creates. It stops short of describing permissions or error modes, but the key side effect is disclosed.

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 'WRITE: create one record', then necessary context in tight sentences. No filler; every clause (mandatory fields, return value, endpoint, no retry) 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 create tool with nested dynamic fields and no output schema, the description covers the critical concerns: mandatory fields, where to find them, the return value, and the no-retry behavior. It omits error handling and permission requirements, but is otherwise sufficient to call 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 coverage is 100%, so the baseline is 3, but the description adds actionable parameter guidance beyond the schema: all mandatory fields must be supplied, vtiger_describe_module lists them, and assigned_user_id usually comes from vtiger_get_me. This is real domain-level semantics for the nested fields object.

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?

Starts with 'WRITE: create one record in a module' — a specific verb, resource, and scope. Examples (lead, contact, account, deal, case) make the resource concrete and distinguish it from sibling read/update tools without needing to open schemas.

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?

Clearly tells the agent to send every mandatory field, points to vtiger_describe_module for the list, and explains assigned_user_id via vtiger_get_me. It does not explicitly say when not to use this instead of vtiger_update_record, but the 'create' framing makes the boundary clear.

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

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

Annotations already establish readOnlyHint=true, so the description needn't argue safety; it instead discloses the shape of the payload (catalog of field properties) and that it answers permission questions about create/update/delete on the module. The inclusion of the underlying endpoint (GET /describe?elementType=<module>) reinforces that no state changes. It does not describe response nesting or error behavior, which keeps it below 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?

Two sentences plus a short endpoint reference, with the payload contents front-loaded and the workflow hint second. It is tight, though the first sentence is a noun phrase without an explicit verb, which makes the opening slightly telegraphic.

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 explaining the return value, and it does so by enumerating the field attributes and the CRUD capability flags. For a one-parameter read-only introspection tool this is close to sufficient; only the structure of reference targets and picklist values is left unspecified.

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 schema already explains the module parameter, gives examples (Contacts, Accounts, Leads) and points to vtiger_list_modules. The description's elementType=<module> phrase adds only a light mapping between the argument and the REST parameter, so it meets the baseline rather than exceeding it.

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

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

The description names the resource (a module) and enumerates exactly what is returned: field metadata (name, label, type, mandatory, editable, reference targets, picklist values) plus create/update/delete capability. This clearly separates it from vtiger_list_modules (which only lists names) and from vtiger_query/vtiger_list_records (which fetch data). The verb is implicit ('describe', telegraphed by the name and the GET /describe path) rather than stated outright.

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 before creating or filtering' gives a concrete trigger that ties the tool to the create and query workflow. It does not name specific alternative siblings or exclusions, but the sequencing guidance is actionable enough for an agent to place this call 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, so safety is covered; the description adds real value by naming the endpoint (GET /me) and enumerating returned fields in the absence of an output schema. It also hints at the auth dependency by framing the user as the one 'the credentials belong to'. Missing only failure behavior for invalid credentials.

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 compact sentence plus endpoint reference, with the resource stated first and the return fields parenthetically front-loaded. 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?

Because there is no output schema, the description carries the burden of describing return values, and it does so by listing the four fields. For a zero-parameter, read-only identity call this is nearly complete; only auth-failure behavior is unaddressed.

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. Nothing in the description conflicts with the empty 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?

Identifies a specific resource — the Vtiger user tied to the supplied credentials — and enumerates the returned fields (id, user name, name, email). The verb 'get' is implicit rather than stated, and no sibling is named, but the tool's identity is unmistakable versus record/module/tag 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?

Usage is only implied: an agent can infer this is the way to identify the authenticated user or validate credentials. There is no explicit when-to-use statement, no mention of checking credentials before other calls, and no alternatives listed.

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 readOnlyHint annotation already covers the safety profile, and the description adds that the result is a single record containing all fields. It does not describe error behavior, missing-record handling, or authentication needs, so it adds only moderate behavioral context.

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

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

The description is front-loaded and very tight: one sentence plus the endpoint. It contains no filler, and the key distinction of returning one record with all fields appears immediately.

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

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

For a simple one-parameter read tool with readOnlyHint and no output schema, the description supplies enough context: it names the record form, gives an example id, and says all fields are returned. Minor gaps around not-found behavior remain but are not critical for invocation.

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

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

Schema description coverage is 100%, and the schema already documents the id format and example. The description repeats the id example and endpoint but adds no new semantic 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?

The description clearly states it returns one record by id with all fields, which distinguishes it from list-oriented siblings like list_records and query. It does not explicitly name alternatives such as vtiger_lookup, so it stops short of full sibling differentiation.

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 'by id' implies the usage condition: use this when you already have a record id. However, it gives no explicit guidance on when to choose this over vtiger_lookup, vtiger_query, or vtiger_list_records.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining burden is small, but it adds nothing beyond that: no note on what happens when the record has no tags, whether tags are module-scoped, or how many are returned. The REST endpoint string (GET /tags_retrieve?id=<id>) is implementation detail, not 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 with the resource stated first and no padding. The endpoint sentence is arguably wasted space since it duplicates the schema's id parameter and the tool name, but nothing is bloated.

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-only tool with full schema coverage and a readOnlyHint, this is close to sufficient, but the description says nothing about the returned tag structure (name vs id vs both) or empty-result behavior, which an agent calling it cold would want to know.

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 'id' parameter is documented with a regex pattern and a concrete example (4x2063). The description contributes no additional meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

"The tags on one record" names the resource and the scope (single record) clearly, and the adjacent vtiger_add_tags sibling is obviously different in intent. However, the sentence is essentially a restatement of the title and name, with no verb and no explicit differentiation from vtiger_get_record, which may also surface tag data.

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

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

There is no guidance on when to prefer this over vtiger_get_record or vtiger_query, and no stated preconditions. An agent must infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description contributes beyond that by disclosing the return shape (label plus a has-records indicator) and that results are scoped to the calling user's access rights. It omits ordering and error behavior, but for a no-argument read this is solid added context.

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

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

Two compact sentences, front-loaded with what is returned rather than what it is called. The trailing 'GET /listtypes' is an implementation detail of marginal use to an agent, a small amount of non-contributing content in an otherwise tight description.

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 parameters and no output schema, the description must convey the return shape, and it does reasonably well by naming label and the per-module record indicator plus user scoping. It could be slightly more complete about the result ordering or how to consume the module names downstream, but nothing essential to calling it 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 the schema carries no semantic burden to compensate for. Baseline 4 applies; the description correctly conveys that it is an unfiltered enumeration.

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 (CRM modules) with a clear list semantics and concrete examples (Leads, Contacts, Accounts, Potentials, Cases), which lets an agent recognize the result set immediately. It doesn't explicitly differentiate from list_related_modules or describe_module, but the examples and the 'this user can access' scoping make the tool's identity unmistakable.

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 rather than stated: an agent can infer this is the discovery call to enumerate valid module names before calling describe_module or list_records, but the description never says when to use it or when to prefer list_related_modules. 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?

Adds real context beyond readOnlyHint=true: the vendor caps results at 100 per call, next_offset should be fed back as offset, and full records carry 100+ fields so callers should name fields. These are operational traits the annotations do not cover. It does not mention rate limits or error behavior, keeping it below 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 compact sentences, each carrying information: scope first, then pagination mechanics, then the field-selection warning. The 'builds a SELECT for GET /query' clause is implementation detail but is short enough to justify itself for debugging.

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, and the description still covers what an agent needs: pagination cap and continuation, the AND semantics of filters, and the cost of omitting fields. Combined with a fully documented schema and a read-only annotation, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, fields, offset, filters, order_by and descending, including the AND-combination example. The description largely restates this ('all filters AND-ed', 'pass next_offset as offset') and only adds the practical advice to name fields rather than request everything.

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 a specific verb+resource: records of one module, optionally filtered/sorted/paged, and notes it builds a SELECT for GET /query. It is clear what the tool does, but it does not explicitly contrast itself with the sibling vtiger_query (raw query) or vtiger_lookup, which an agent would need to choose between.

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: 'Records of one module, optionally filtered' tells the agent this is the general listing path, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative such as vtiger_query or vtiger_count_records. The agent must infer routing from sibling names alone.

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

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

readOnlyHint=true already declares the safety profile, and the description reinforces it by citing the GET /relatedtypes endpoint. It does not describe the response shape, ordering, or whether an empty list is possible, so added behavioral value is modest.

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 concept front-loaded and a helpful example; the raw endpoint string is slightly technical filler but does convey the read-only GET semantics.

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, the description covers what it does and gives an example; only the return value (a list of module names) is left implicit, which is a minor gap with no output schema 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 parameter description already names valid modules and points to vtiger_list_modules. The description only adds the mapping of the 'module' argument to the elementType query parameter, which is marginal.

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 clearly that it returns the modules related to a given module, with a concrete example (Accounts relate to Contacts, Potentials, Cases, Documents). It is distinguishable from vtiger_list_modules by the 'related to' framing, although it never names that sibling 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 discovery step before listing related records, but there is no statement of when to prefer it over vtiger_list_modules or vtiger_describe_module, and no prerequisites or exclusions.

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

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

readOnlyHint already declares this is a safe read, so the description's added value is limited to the exact-match semantics and the 'GET /lookup' endpoint hint. It says nothing about what a hit looks like, whether all matching modules are returned, or behavior when nothing matches.

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, front-loaded sentences with the key constraint ('exact') early. The trailing 'GET /lookup' is low-value implementation detail for 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?

For a read-only lookup with no output schema, the definition should at least hint at result shape (matched records per module, empty result behavior). It stops short, leaving the agent to inspect the response by trial.

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 type/value/modules are fully documented including enum, length bounds, and default modules. The description only reinforces 'exact' matching and 'one or more modules', adding marginal meaning beyond the schema.

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

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

States a specific verb and resource (find records), the searchable modules, and the two lookup keys (exact email or phone). The 'exact' qualifier separates it from a general query tool, though it never names the sibling it supersedes.

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 'exact email address or phone number' versus broader search siblings like vtiger_query or vtiger_list_records, but no when-to-use/when-not or alternative is stated explicitly.

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, so the safety profile is covered. The description adds meaningful constraints beyond that: only SELECT is accepted, one module only, no joins, no grouping brackets, and a 100-record cap per call. These are useful behavioral limits that help an agent form valid queries.

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 compact sentences with the query template front-loaded and constraints packed efficiently into the second. Every clause earns its place by defining syntax, scope, or limits.

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-only query tool with full schema coverage and an annotation covering safety, the description supplies the remaining essentials: accepted syntax, scope restrictions, and record limits. Nothing critical to forming a valid call is missing, and return format need not be explained without an output schema.

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

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

Schema coverage is 100% and the schema includes a concrete example query, so the baseline is already strong. The description adds value by documenting the accepted grammar (SELECT <fields|*|count(*)> FROM <Module> [WHERE ...] [ORDER BY ...] [LIMIT offset,count]) and the structural restrictions, which go beyond the schema's example.

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 and resource: 'Run your own read-only query' with a SELECT template against a module. This clearly distinguishes it from fixed-purpose siblings like vtiger_list_records or vtiger_count_records, though it never names those alternatives 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 'your own' query and the syntax template, which suggests this tool is for custom SELECTs rather than predefined listings. However, there is no explicit routing guidance such as 'use vtiger_count_records for simple counts' or 'use vtiger_list_records for unfiltered lists', leaving the agent to infer when this tool is preferable.

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

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

Annotations declare destructiveHint and idempotentHint, and the description adds genuinely new context: unnamed fields are preserved, the updated record is returned, and the call is not retried. It does not cover auth requirements or what happens if an unknown field name is supplied, which is a notable gap for a mutation tool.

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

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

Extremely tight and front-loaded with the WRITE marker and the core semantics. The 'POST /revise' fragment is close to noise for an agent, but the rest of the sentence carries real 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?

There is no output schema, and the description fills that hole by stating it returns the updated record. Combined with the partial-update guarantee and retry policy, an agent has enough to call it correctly, though error behavior for bad field names is unaddressed.

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 the id pattern and the fields-object key/value conventions fully documented in the schema itself. The description only echoes 'named fields' and adds no format or validation detail beyond that, 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 the specific verb and resource ('change only the named fields of an existing record') and pins down partial-update semantics, which is what separates it from vtiger_create_record. Naming the vendor 'revise' call and the POST /revise endpoint leaves no ambiguity about the operation.

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 'existing record' wording imply this is the mutation path for records that already exist, but it never explicitly says when to prefer it over vtiger_create_record or that field names must be resolved via vtiger_describe_module. 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.