esmole-mcp

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

With no annotations, the description carries the disclosure burden and does add valuable behavior: it reveals where the connection is persisted for each scope and that credentials are stored acceptably via two auth schemes, plus optional ssh tunneling and TLS verification. It omits important traits: whether an existing name is overwritten or rejected, whether credentials are written in plaintext to .esmole.json, and whether the connection is validated on add.

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, no filler, and the most decision-relevant fact (scope semantics) is front-loaded immediately after the purpose statement. Every clause 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 13-parameter mutation tool with a nested object, no annotations and no output schema, the description covers the top-level shape but not overwrite/idempotency behavior or the nested ssh credential options. An agent could call it, but might pick the wrong auth fields or silently clobber an existing connection.

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 0% across 13 parameters (including a nested ssh object), so the description must compensate. It covers scope, user/password, apiKey, readonly, scheme, verifyTls and the existence of ssh, but leaves name, host, port, type, queryTimeoutMs, and all nested ssh fields (agent, hostKey, privateKeyPath, passphrase) undocumented.

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 named Elasticsearch connection" — which clearly separates it from update_connection, remove_connection, list_connections and test_connection. It does not name those siblings explicitly, but the create semantics are 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?

Gives real guidance on the scope choice (default 'global' writes to the user store, 'project' writes to .esmole.json in the project root) and lists auth alternatives (user/password vs apiKey). However, it never says when to use this versus update_connection (e.g. what happens if the name already exists) or test_connection (validate before saving).

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

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

With no annotations, the description carries the burden, and 'Wraps GET /_cluster/health' does useful work by signalling a read-only, non-mutating call. It does not disclose failure behavior (unreachable cluster, bad connection id) or whether the result is cached/real-time, which leaves real gaps for an unannotated 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?

Two sentences, front-loaded with the purpose and follow-up with the API mapping. No filler and nothing buried.

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

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

The description roughly covers the return shape (status, node and shard counts), which partially offsets the absent output schema. However, for a tool with zero annotations and an undocumented required parameter, it leaves the agent without enough to call it confidently across multiple clusters/connections.

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 required parameter 'connection' has 0% schema description coverage and the description says nothing about it — not whether it is a connection name from list_connections, a URL, or an alias. With the schema silent, the description needed to compensate and does not.

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 resource and what it returns (status, node and shard counts) and identifies the underlying API endpoint, so an agent knows immediately this is a health/diagnostic read. It is distinguishable from siblings like es_list_indices or es_search, though it doesn't explicitly say so.

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 statement of when to call this versus alternatives such as es_request or es_list_indices, and no prerequisites. An agent must infer the diagnostic use case from the name 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the default output behavior ('flat field:type list', 'compact, token-cheap') and the raw alternative, but does not explicitly state read-only safety, permission requirements, or error behavior for missing indices/connections.

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 purpose and followed immediately by the only non-obvious output option. No wasted words.

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

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

For a simple read retrieval tool with no output schema, the description adequately explains the returned shape and the raw alternative. The main omission is enough detail about the connection and index parameters to fully compensate for the zero schema descriptions.

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 0%, so the description should compensate for all three parameters. It explains only the 'raw' parameter meaningfully; 'index' is only implied by 'an index mapping', and 'connection' is not addressed at all.

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 a specific verb and resource: 'Return an index mapping'. It also specifies the output shape ('flat field:type list') and an alternative mode ('raw=true'), which distinguishes it in practice from a generic request tool. It does not explicitly name which sibling to use instead, 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?

Usage is implied by 'Return an index mapping' and the raw=true option gives a clear conditional for output mode. However, there is no explicit guidance on when to prefer this over es_request or es_list_indices, and no when-not-to-use guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the underlying endpoint ('GET /_cat/indices') and the return fields, which implies a read-only operation, but it omits permissions, failure behavior, and whether the pattern supports wildcards or regex.

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 operation front-loaded and no wasted wording. The endpoint note adds useful context without bloat.

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 tool, the description covers the operation and return metrics, but it leaves the required 'connection' parameter undocumented and does not clarify pattern syntax. Given no annotations and no output schema, that is adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate fully. It only indirectly explains the 'pattern' parameter via 'matching a pattern' and says nothing about the required 'connection' parameter, leaving half the inputs undocumented.

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 ('List indices') plus scope ('matching a pattern') and return contents ('health, doc count and store size'). It does not explicitly differentiate from siblings like es_search or es_cluster_health, but the purpose is clear enough to select the tool.

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

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

Usage is implied: use this when you need to list Elasticsearch indices. However, the description gives no explicit when-to-use guidance, no exclusions, and never mentions alternatives such as es_request or es_search.

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

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

Without annotations, the description carries the full burden and does so well: it discloses the return shape ({status, body}), the error format for 4xx/5xx ('HTTP <status> <type>: <reason>' plus trimmed body), the requirement for string bodies with NDJSON, and the readonly connection restrictions. It omits details like timeout behavior or retries, but covers the essentials.

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 dense and front-loaded: it opens with the core purpose, then details return and error formats, and finally lists readonly restrictions. Every sentence provides useful information with no filler, though it could be slightly more structured for faster scanning.

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

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

Given the lack of an output schema and annotations, the description compensates by explaining the return value and error format. It also covers the readonly whitelist, which is critical for safe invocation. The main gap is the undocumented `params` parameter, but overall it is sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 40%, so the description must compensate. It adds value for the `body` parameter by explaining the string requirement for NDJSON. However, the `params` parameter is completely undocumented in both description and schema, and `connection` is only briefly referenced. The description adds meaningful context for one parameter but leaves significant gaps.

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

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

The description clearly states a specific verb and resource: 'Generic Elasticsearch REST passthrough: any method, any path.' It distinguishes itself from specialized siblings like `es_search` and `es_get_mapping` by being a generic escape hatch, though it doesn't explicitly recommend when to choose this over the specialized tools.

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

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

The description implies usage through examples (e.g., string body for NDJSON) and constraints (readonly connections allow only reads), but it does not provide explicit guidance on when to use this tool versus the specialized sibling tools like `es_search` or `es_get_mapping`. The agent must infer that this is the fallback option.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the size default of 10, the non-obvious rule that aggs with no query forces size to 0, the {status, body} return envelope, and that 4xx/5xx surfaces an ES root cause error. Authentication/connection assumptions are the main undisclosed trait.

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?

Dense and front-loaded: endpoint mapping first, then parameter mapping, then pagination and projection guidance, then return/error behavior. Every clause conveys a distinct fact 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 12-parameter nested-object tool with no output schema and no annotations, the description covers return shape, error semantics, defaulting behavior, and param mapping. The remaining gap is the relationship to es_request and the meaning of the required connection parameter.

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 only 42%, and the description compensates by mapping the undocumented body keys (sort, from, search_after, track_total_hits, highlight, script_fields, _source) and clarifying that query is DSL only, not a full body. It omits the size ceiling of 1000 and leaves the connection parameter entirely unexplained.

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 ('Search an index') and immediately grounds it in the underlying endpoint ('Wraps POST /{index}/_search'), so an agent knows exactly what it does. It does not explicitly differentiate itself from the sibling es_request, which could also issue a _search body, so it stops short of a 5.

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

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

The description gives operative advice on how to use the tool ('Page with from+size or sort+search_after', 'Use source to project fields and keep responses small'), which implies the intended usage pattern. However it never says when to pick this over es_request, nor names prerequisites, so alternative selection is left to inference.

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

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

With no annotations, the description carries the load and does so well: it discloses the project-layer resolution mechanism (walking up from the project dir to find .esmole.json), the global fallback to the user store, that invalid entries and broken files appear in output, and that secrets are redacted. It stops short of stating ordering, deduplication between layers, or error behavior, 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?

Two sentences, no redundancy, and the core purpose is front-loaded before the parenthetical path-resolution detail. Every clause adds information the agent could not get from structured fields.

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, params, or annotations exist, so the description must explain what comes back, and it largely does (layer name, invalid entries, broken files, redacted secrets). Slightly short of complete because the shape of an "invalid entry" or "broken file" record is left unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies a parameterless, whole-store 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?

Specific verb plus resource ("List Elasticsearch connections") with the added dimension of which layer each connection comes from. It clearly reads as the non-mutating inventory tool among siblings like add_connection, update_connection, and remove_connection, and it is distinct from the es_* query tools.

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

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

Usage is only implied by the verb "List"; there is no explicit statement of when to call this versus test_connection or the es_* tools, and no prerequisites or exclusions. An agent can infer it is the discovery step before mutation, but it must do the inferring itself.

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

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

With no annotations at all, the description carries the full burden and does disclose real behavior: it removes even invalid entries and drops the cached client/tunnel, which tells the agent this is destructive to runtime state. It omits failure behavior when the name doesn't exist and whether the removal is reversible.

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 front-loaded sentence with no filler. The primary action comes first and the side effects follow in the same breath.

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 destructive, annotation-free, no-output-schema mutation tool, the description covers the action and two side effects but leaves out error behavior, idempotency, and confirmation that the effect is permanent. An agent still has to guess at the edges.

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 0%, so the description must compensate, and it only partially does. 'By name' confirms the sole parameter is the connection identifier and that invalid entries are still matched, but it doesn't clarify whether this is a display name, ID, or the registered key, nor the expected format.

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

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

States a specific verb+resource: remove an ES connection by name. This clearly separates it from add_connection, update_connection and test_connection in the sibling list. The phrase 'from the layer it lives in' is somewhat opaque domain jargon, which keeps it short of a 5.

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

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

Usage is only implied: an agent infers it should call this when it wants a connection gone. There is no statement of when to prefer update_connection, no prerequisites, and no note about what to do if the connection might still be in 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 no annotations, the description carries the full burden. It usefully discloses that the check traverses the ssh tunnel and that the response contains server version and latency, but says nothing about failure behavior (error vs. negative result), authentication needs, or timeout characteristics for what is inherently a network round trip.

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 verb and resource, with the scope qualifier and return payload following. No filler text.

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

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

For a simple, one-parameter read-only diagnostic tool with no output schema, the description conveys what is checked and roughly what comes back. The only real omission is disambiguating the 'name' parameter and stating what a failed test looks like.

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 required parameter 'name' has 0% schema description coverage and the description never clarifies whether it is a stored connection identifier, a host, or a URI. The description mentions 'an ES connection' only obliquely, so the agent must guess which value to supply.

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 (verify) and resource (an ES connection), plus the end-to-end scope including the ssh tunnel. None of the sibling tools (update/list/add/remove_connection, the es_* operations) perform this check, so an agent can select it unambiguously.

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 nature of the call implies usage (confirm a connection is healthy, e.g. after add_connection or before es_search), but the description never states when to use it versus es_cluster_health or when not to bother. 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?

With no annotations, the description bears the full burden and does substantial work: it discloses that null deletes a field, that ssh merges field-by-field rather than replacing wholesale, and that queryTimeoutMs controls the per-request deadline with null restoring the 60 s default. Undisclosed: permission requirements, behavior when the named connection is missing from both layers, and whether changes take effect on live connections.

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

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

Three dense sentences, front-loaded with the verb and scope, then the mutation semantics, then the one non-obvious field. The inline JSON examples earn their place, though the sentence structure is somewhat crammed with parentheticals.

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 nested-object mutation with no annotations and no output schema, the merge/delete semantics are well covered, but return behavior (does it return the updated connection?) and failure modes (connection not found, invalid hostKey pattern, conflicting ssh fields) are absent. An agent knows how to shape the patch 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?

Schema description coverage is 0%, so the description must compensate; it explains the null-deletion convention, the nested ssh merge rule, and queryTimeoutMs semantics, which covers the trickiest parts. However, the patch object contains a second `name` field (rename, with its own regex) that the description never mentions and whose relationship to the top-level `name` identifier is left ambiguous; port, user, scheme, apiKey, verifyTls and readonly are also unaddressed.

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: 'Patch an ES connection by name', plus the scope clarification that it applies to the layer the connection lives in (project or global). This distinguishes it from add_connection and remove_connection without naming them explicitly, though a direct sibling reference would have sealed a 5.

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

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

Usage is implied by the word 'patch' (partial update of an existing connection, not creation), but there is no explicit 'use this instead of add_connection when...' or prerequisite guidance. The null-removal example describes mechanics rather than when to choose this tool over test_connection or add_connection.

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