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

Annotations declare a non-readonly, non-destructive, non-idempotent write, and the description adds real context beyond them: the profile is registered at runtime, replaces an existing entry, and is tested as part of the call. The security-relevant rule 'Passwords are never passed here: use password_env (name of an environment variable set in mcp.json)' is exactly the kind of credential handshake an agent needs and no annotation supplies it. It still doesn't say what happens when the test fails or whether the profile persists across restarts.

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 lines: purpose first, then host/uri syntax, then auth modes and the credential rule. Grouped by parameter family and free of filler, though it spends its budget on the already-obvious connection fields while omitting higher-impact ones.

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

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

For a 14-parameter mutation tool with no output schema and zero schema descriptions, the description covers only the happy path of naming a host and an auth mode. An agent cannot confidently set make_default, readonly, tls, replica_set or direct_connection from this definition, and the return value of the 'test it' step is 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 0% across 14 parameters, so the description carries the full burden. It explains only host, uri, auth and password_env (with useful format examples and an enumerated auth mode list), leaving tls, user, database, readonly, auth_source, replica_set, make_default, direct_connection and tls_allow_invalid_certificates completely undocumented — several of which materially change behavior (make_default, readonly).

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 concrete verb and resource — 'Register (or replace) a connection profile at runtime and test it' — which an agent can clearly separate from list_connections, test_connection and remove_connection. It only lacks an explicit contrast with the siblings it overlaps with (test_connection in particular).

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 'at runtime' framing implies this is for adding a profile mid-session rather than the initial config, but no when-to-use / when-not-to-use guidance is given. The overlap with test_connection (which presumably tests an already-registered profile) and with remove_connection is left for the agent to infer.

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 description does add real value beyond annotations by disclosing write-capable stages ($out/$merge) that persist results, contradicting readOnlyHint=true and destructiveHint=false. It also explains that limit defaults to the profile's max_docs, which is genuine behavioral context. But the core safety claim conflicts with the declared annotations, leaving an agent unsure whether this call can mutate data.

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

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

Three short sentences, front-loaded with the action and followed by the two constraints an agent most needs. Dense and free of filler, though the collation example is slightly detailed relative to the omitted parameters.

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 an 8-parameter tool with no output schema and no param descriptions, the description covers the highest-risk items (write stages, limit default, collation) but leaves half the surface undocumented and never states what the result looks like or how errors surface. Adequate but visibly partial.

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 carries the full burden, yet it explains only pipeline, limit, and collation (with a useful Turkish-locale example). Five parameters — database, collection, connection, max_time_ms, allow_disk_use — get no explanation at all, and max_time_ms/allow_disk_use are non-obvious enough to need one.

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: 'Run an aggregation pipeline (JSON array of stages)'. That is clearly distinguishable from siblings like find, count_documents, and distinct. It does not explicitly say how it differs from run_command, which could also execute arbitrary server-side logic, so it stops short of a 5.

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

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

Usage is only implied by the mechanism (pipeline = aggregation), with a conditional note that $out/$merge are allowed unless the profile is read-only. There is no explicit when-to-use-this-vs-find/run_command guidance and no statement of prerequisites or failure modes. Enough to orient, not enough to route confidently.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the actual metrics returned (data/storage/index sizes in MB, average document size, capped flag), which matters because there is no output schema. It does not say whether it errors on a missing collection or how expensive the call is.

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?

One short fragment with no padding, but it is not a sentence and lacks a leading statement of what the tool does, so the return-value list is doing double duty as the purpose.

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

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

Because there is no output schema, listing the returned metrics is genuinely useful, but the definition still leaves an agent unsure how to supply database and connection, or whether the call targets one collection by name. A collection-scoped read tool needs at least that much.

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 three parameters (database, collection, connection), and the description says nothing about any of them — not that database/connection are optional with defaults, nor what they resolve to. With low coverage the description is expected 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?

The description is a noun-phrase list of returned metrics rather than a verb+resource statement; combined with the name collection_stats an agent can infer it reports statistics for a collection, but the description itself never says 'returns stats for a collection'. It does distinguish itself from count_documents by enumerating storage/index/capped info, which count_documents would not provide.

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 when-to-use guidance at all: nothing says to prefer this over count_documents for document counts, or over server_status / list_collections. No mention of prerequisites such as which database or connection is targeted.

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 read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond them: estimated=true is fast but silently ignores the filter, and collation changes matching semantics (Turkish İ/i, I/ı). That filter-ignoring caveat is the kind of detail an agent would otherwise get wrong.

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 core action, then two compact clauses for the non-obvious parameters. No filler; the collation clause is terse but carries concrete matching rules an agent can copy.

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, 6 parameters at 0% schema coverage, and the description leaves database/connection semantics and the shape of the count result unstated. Adequate for the count-specific options, but not complete for a tool with this many undocumented inputs.

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 0% across 6 parameters, so the description must compensate and only partly does: it explains estimated and collation meaningfully (with a concrete locale/strength example) and implies filter's role in the first sentence. database, connection, and the required collection string get no semantic explanation 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?

Specific verb+resource: 'Count documents matching a filter' tells the agent exactly what it computes. It does not name a sibling (e.g., find) as the alternative when the actual documents are needed, so it stops short of full 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 estimated=true clause gives a real decision rule (fast metadata count that ignores the filter), which is a usage condition. But there is no explicit guidance on when to prefer this over find/aggregate for counts, nor any prerequisite context such as required collection or connection setup.

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 this is a non-readOnly, non-destructive, non-idempotent write. The description adds valuable context by stating options are forwarded to the underlying 'create' command, which tells an agent that server-side create semantics apply. It omits what happens if the namespace already exists, required permissions, and whether partial option dictionaries are merged or rejected.

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 action and then the option syntax. The examples are compact and each earns its place by illustrating a distinct option class, though the run-on example list could be slightly tighter.

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 annotations covering the safety profile and no output schema needed, the main remaining gaps are behavioral: no statement about duplicate-name failure, no defaulting rules for database/connection, and no indication of what the call returns. Adequate for a simple create, but an agent must guess at the target namespace.

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 carries the load. It does compensate well for the 'options' parameter with four concrete example shapes (validator, capped, timeseries, viewOn/pipeline), but leaves 'database' and 'connection' completely unexplained and does not clarify whether 'name' accepts a namespaced form.

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

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

States a specific verb and resource ('Create a collection or view'), and the view distinction plus the option examples make clear this covers both plain collections and views — enough to separate it from siblings like create_index, rename_collection, or insert_documents.

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

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

The mention of viewOn/pipeline implies when the view path applies, but there is no explicit 'use this when...' guidance, no note on which connection/database the collection lands in, and no mention of alternatives such as run_command for raw create commands.

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 this is not read-only and not destructive; the description adds that TTL indexes and partial filters are expressible, which is real behavioral context. However, it says nothing about what happens if an identical index already exists, whether creation blocks on large collections, or permission requirements — meaningful gaps for a mutating, 9-parameter 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 dense sentences, front-loaded with the action then the key syntax, every clause doing work. The nested-quote formatting is slightly awkward but nothing is redundant.

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

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

It documents the two hardest concepts (keys syntax, TTL/partial filter) but leaves six of nine parameters — name, sparse, unique, database, collection, connection — entirely undescribed, and there's no output schema or annotation detail to fall back on. For a 9-param mutation tool, that leaves the definition only partially 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 coverage is 0% and the keys parameter lacks even a type in the schema, so the description's concrete spec examples ({"customerId": 1, "createdAt": -1}, {"title": "text"}, {"loc": "2dsphere"}) plus the explanation of expire_after_seconds and partial_filter carry the full burden and do so with real specificity.

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 an index") with concrete key-spec examples that clarify what an index spec looks like in this tool's idiom. It doesn't explicitly distinguish itself from siblings like drop_index or list_indexes, but the action 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?

No statement of when to create an index versus alternatives, no prerequisites (permissions, connection/database selection), and no guidance on how it interacts with drop_index or list_indexes. Usage is only implied by the verb.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that—no mention of permissions, connection requirements, pagination, or how results are ordered or limited.

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

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

The description is a single sentence with no filler, so it is concise. However, it is a parenthetical field list rather than a front-loaded statement of the tool's action, which weakens its structure as a tool 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 three undocumented parameters and no output schema, the description should explain active_only and min_seconds and clarify the tool's relationship to kill_op. Instead it only enumerates some output fields, leaving key invocation details 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 0%, so the description must compensate, but it instead lists output fields (opid, op, namespace, seconds running, client, command summary) that do not correspond to the input parameters (connection, active_only, min_seconds). It provides no meaning for any of the three 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 'Running operations (opid, op, namespace, seconds running, client, command summary)' implies listing currently running operations, but it lacks a clear verb and reads as a field inventory rather than a definition of purpose. It does not distinguish itself from siblings like kill_op or server_status, leaving the agent to infer the action.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as kill_op or server_status. The only implied context is the word 'running', which is insufficient to route an agent among many sibling tools.

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

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

Annotations already flag this as destructive and non-idempotent, and the description adds useful behavioral detail: it explains whether one or all matching documents are deleted and imposes a confirmation guard for empty filters. It does not describe permissions or return behavior, but the core destructive semantics are well 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?

The description is two short sentences with the deletion scope and confirmation requirement front-loaded. Every sentence adds useful information, with no wasted wording.

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 tool with 7 parameters, required fields, no output schema, and 0% schema description coverage, the description covers only part of the surface. It addresses the destructive scope and confirmation guard, but omits meaning for most parameters and any response behavior.

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 carry parameter meaning, but it only explains `many` and `confirm_all` and notes the empty-filter case. It leaves `collection`, `filter`, `database`, `connection`, and `collation` undocumented, which is a substantial gap for 7 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 states a specific verb and resource: deleting documents, with the distinction between first matching and all matching documents. That is clear enough for an agent to identify the operation, though it does not explicitly contrast with sibling tools like update_documents or drop_collection.

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 concrete usage guidance for the `many` flag and states that an empty filter requires `confirm_all=true`. It does not name alternatives or explain when to choose another deletion-related tool, so it falls short of 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.

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

Annotations already declare read-only, idempotent, non-destructive behavior with openWorldHint=false. The description adds a useful operational limit ('at most 5000 values'), which is not in annotations, but does not cover permissions, error behavior, or return format.

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 core purpose and result cap before the collation example. The collation detail is useful but slightly idiosyncratic; overall it is efficient with little wasted text.

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

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

For a read-only tool with no output schema, 6 parameters, and 0% schema coverage, the description provides some essential context (field, filter, collation, result cap). However, it omits database/connection/collection usage and does not clarify output shape or pagination behavior beyond the 5000-value cap.

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 carry the burden. It meaningfully explains field, filter, and collation (with a concrete Turkish example), but leaves database, connection, and collection semantics 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?

The description clearly states the tool returns distinct values of a field, optionally filtered, which is a specific verb+resource. It does not explicitly differentiate from siblings like find or aggregate, but the operation is clear enough to distinguish.

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 via 'optionally within a filter' but gives no explicit guidance on when to use this tool versus find, aggregate, or count_documents. There are no exclusions or alternatives named.

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 and idempotentHint=false, so the safety profile is covered. The description still earns credit for disclosing the exact scope of destruction (documents plus indexes, not just the namespace) and the confirm_name guard that prevents accidental drops.

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, zero padding, with the destructive scope front-loaded ahead of the confirmation requirement. Every clause carries information an agent needs before calling.

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 tool whose annotations already flag destructiveness, the description supplies destruction scope and the confirmation protocol. Remaining gaps are minor: default database/connection resolution and behavior on a missing collection, with no output schema to explain the result.

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 carries the burden for four parameters. It explains confirm_name's repeat-the-name semantics well, but says nothing about database, connection, or what happens if collection doesn't exist; it only partially compensates for the coverage gap.

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 ('Drop a collection') and immediately scopes the blast radius ('with all its documents and indexes'). That phrasing cleanly separates it from delete_documents (documents only), drop_index, and drop_database, so an agent can route without opening a 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?

The description implies when to use it (full collection removal) but never names alternatives or exclusions, e.g. 'use delete_documents to remove documents while keeping the collection' or 'use drop_database for the whole database'. Usage is inferable but never 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?

The annotations already mark this as destructive and not idempotent. The description adds useful behavioral context: a confirmation parameter is required, and certain system database names are rejected. It does not describe irreversibility or permission requirements in more detail.

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

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

Three short sentences, front-loaded with the action and the critical confirmation requirement. There is no wasted text.

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

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

For a destructive tool, it covers the essential safety behavior: confirmation and refused targets. It is slightly incomplete because the optional connection parameter is undocumented, but the annotations already communicate the destructive profile.

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 carry parameter meaning. It explains confirm_name well and partially constrains database via refused values, but it does not explain the optional connection 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?

It states a specific verb and resource: "Drop a whole database." This clearly distinguishes it from sibling tools such as drop_collection and drop_index.

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 important guardrails: confirm_name must repeat the database name, and admin/config/local are refused. However, it does not explain when to use this tool instead of related destructive tools such as drop_collection.

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 and idempotentHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral constraint (the _id index is protected) but is silent on failure behavior when the index doesn't exist and on the performance consequences of removing an index used by 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?

Two short sentences, front-loaded with the action and followed by the discovery pointer and the constraint. No 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 destructive mutation with zero schema documentation and no output schema, the description covers only the _id gotcha. An agent still lacks the target-resolution semantics (which database/connection apply) needed to call it confidently.

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

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

Schema description coverage is 0% across four parameters, so the description must carry the load — but it only clarifies that `name` is the index name. It never explains how collection pairs with name, nor what the nullable `database` and `connection` parameters default to when omitted.

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 ("Drop an index") and points to list_indexes for discovery. It is clearly distinct from sibling create_index/drop_collection/drop_database, 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?

Names list_indexes as the way to obtain valid index names and states an explicit exclusion (the _id index cannot be dropped). No guidance on when to drop vs. rebuild an index or what happens to queries afterward, but the selection context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real value beyond that by disclosing the limit default ('profile's max_docs (100)') — a behavioral default invisible in the schema — plus the collation semantics. It still says nothing about error handling, max_time_ms behavior, or how database/connection defaults resolve.

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 purpose sentence, then dense examples with no filler. The Turkish-collation digression is long but earns its space by documenting a genuinely non-obvious matching behavior; no sentence 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 10-parameter tool with no output schema and zero schema descriptions, the definition covers the query-shaping parameters well but omits four parameters (skip, database, connection, max_time_ms) and says nothing about what a result set looks like or how pagination interacts with skip/limit.

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 0% across 10 parameters, so the description must carry the load. It gives useful concrete forms for sort (both object and array-of-pairs syntax) and collation (workable locale/strength example), but leaves skip, database, connection, and max_time_ms entirely undocumented — about half the surface.

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 ('Query documents') and immediately clarifies that filter/projection/sort are Extended JSON. It does not differentiate itself from close siblings like aggregate, count_documents, or distinct, so an agent must infer that this is the plain-find path.

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 explains syntax but never states when to choose find over aggregate, count_documents, or distinct, nor any prerequisites. With 27 sibling tools in a MongoDB server, some routing guidance would materially help selection.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that results come from a random sample and by explaining the return format, including present_pct and nested path notation.

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 tight sentences with no wasted language. It is front-loaded with the core action and then specifies the return shape, both of which are useful for the caller.

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?

Annotations cover the safety profile, and the description explains the output shape despite there being no output schema. However, with four parameters and 0% schema description coverage, the description is incomplete regarding parameter meaning and optional connection/database context.

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

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

Schema description coverage is 0%, and the description does not explain the four parameters. It only hints at sample_size through the phrase 'random sample'; database, collection, and connection are not described at all, so the description does not compensate for the undocumented schema.

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

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

The description uses a specific verb and resource: infer document structure from a random sample. It also defines the returned field paths, BSON types, and present_pct, making the tool distinguishable from generic query tools, though it does not explicitly name sibling alternatives.

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

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

Usage is implied by the description of sampling and schema inference, but there is no explicit guidance on when to use this tool versus alternatives such as collection_stats, find, or list_indexes. 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 this is a write operation, non-idempotent, and non-destructive. The description adds useful behavioral context: it returns inserted _ids and ordered=false continues inserting after a failing document. It still omits permissions, duplicate-key behavior, and the default ordered=true stopping 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 sentences, both front-loaded and purposeful. The insert behavior and return value come first, followed by the important ordered=false exception.

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

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

The description covers the core insert purpose, return value, and failure-handling nuance, and annotations cover the safety profile. However, with five parameters at 0% schema description coverage and no output schema, the missing collection/database/connection semantics and duplicate-error behavior leave meaningful 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 for all five parameters. It explains that documents may be a single object or array and what ordered=false does, but collection, database, connection, and default ordered=true behavior remain 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: insert documents, accepting either one JSON object or a JSON array, and returning inserted _ids. The operation is inherently distinguishable from replace_document and update_documents, 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?

There is no explicit guidance on when to use this instead of replace_document or update_documents, nor are prerequisites or exclusions given. The only conditional guidance is the ordered=false failure behavior, which is more about parameter semantics than tool selection.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the danger profile is covered by structured data. The description adds no behavioral detail beyond that — nothing about whether partial writes survive, what happens if the op finished already, or what a successful response contains. Against an already-strong annotation set, this is the expected minimum, not a gap that sinks it.

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 short sentence with the action front-loaded and the id source inline. Nothing wasted, nothing 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?

Safety is covered by annotations and there is no output schema to explain, but a destructive tool with an undocumented second parameter and no statement of effect (abort semantics, confirmation needs) leaves an agent guessing on the connection dimension. Adequate, not 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 0%, so the description must carry all parameter meaning. It explains only the required opid (its source in current_ops) and never mentions the optional 'connection' parameter, leaving it entirely undocumented in both schema and description — a real ambiguity in a toolset with multiple connections (list_connections, add_connection are siblings).

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 (kill) and resource (a running operation) plus the identifying key (opid), which cleanly separates it from every sibling in the list — none of the others terminate work in flight. Naming the source of the id, 'from current_ops', also anchors it to a known 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 parenthetical '(from current_ops)' gives an explicit prerequisite workflow: call current_ops first to obtain the opid. It does not state when-not to use it (e.g. after the op already completed, or on idle ops), so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that counts are 'estimated' and that results include views as well as collections, but says nothing about cost, permissions, or behavior when database/connection are omitted.

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 lines with the resource and return shape front-loaded and the filter example second; nothing is redundant. Brevity tips into under-specification rather than padding, but the structure itself is efficient.

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

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

A four-parameter tool with no output schema and zero schema description coverage needs the description to carry more weight. As written, an agent cannot tell what happens when database is null, what include_counts=true costs, or how connection scoping works.

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 for four parameters and only handles one — name_filter gets a concrete regex example. The database, connection, and include_counts parameters are left entirely to their titles, and the interaction between include_counts and the 'estimated document count' claim is not explained.

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

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

The description names the specific resource (collections and views of a database) and the returned fields (type, estimated document count), which distinguishes it from siblings like list_databases and list_indexes. It lacks an explicit verb, relying on the tool name to supply 'list', but the resource and scope 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?

No statement of when to use this tool versus list_databases, collection_stats, or infer_schema. The name_filter regex example is the only piece of operational guidance, and it addresses syntax rather than tool selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: passwords are redacted from output and broken profiles surface their error rather than failing the call — both non-obvious behaviors an agent needs.

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 sentence with the resource front-loaded and a compact parenthetical carrying two useful behavioral facts. 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 zero-param, no-output-schema tool, the description covers what comes back (profiles, redacted passwords, error state for broken entries). It could go slightly further by noting the identifying field an agent would pass to test_connection/remove_connection, but the essentials are present.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to explain inputs, and it doesn't waste space doing so.

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 ('configured MongoDB connection profiles'), which cleanly separates it from the many list_databases/list_collections siblings. It stops short of explicitly naming an alternative, but the resource itself 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?

Usage is only implied: an agent can infer this is the discovery step before test_connection or add_connection, but the description never says when to call it or what to do next. No exclusions or alternatives are named.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description does add value beyond that: results are privilege-filtered per login and include on-disk size, which tells the agent to expect a possibly partial list. It says nothing about ordering, pagination, or what an empty/denied result looks like, so a 3 is right.

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 well-formed sentence with the resource, the returned attribute, and the visibility constraint front-loaded. No filler, nothing repeated from the annotations or schema.

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

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

For a simple read-only enumeration with full annotation coverage and no output schema, the description covers the essentials of what is returned. However, the connection parameter is undefined and the size metric's units/format are unspecified, both of which an agent needs before calling. 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% and the single parameter ("connection") is never mentioned in the description. An agent gets no explanation of what a connection refers to, whether it can be omitted, or how the nullable default is resolved. With low coverage the description was expected to compensate, and it 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?

Names a specific verb and resource ("List databases") and adds two distinguishing facts: results include size on disk and are filtered to those visible to the login. The resource alone clearly separates it from siblings like list_collections and list_indexes. It stops short of explicitly naming the nearest alternative, so it lands at 4 rather than 5.

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

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

There is no statement of when to use this versus list_collections, collection_stats, or server_status, and no prerequisites or ordering advice. The parenthetical scope note ("only the ones the login may see") hints at a discovery use case but is a scope constraint, not usage guidance. An agent must infer that this is the top-level enumeration call.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, and the description still adds value by disclosing the shape of the returned data (keys plus index options like TTL and partial filters). It stops short of saying how database/connection defaults resolve, but the return-content disclosure is a genuine addition given there is no output schema.

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

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

One compact sentence with the resource and the notable option types front-loaded; nothing is wasted. It is a fragment rather than a full sentence, but that costs no clarity here.

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 listing tool the description covers purpose and return content adequately, and annotations cover safety. It is still incomplete on how database and connection selection work and offers no hint about the return container (list vs. map) in the absence of 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 description coverage is 0% across three parameters, and the description only implicitly references 'collection'. The optional database and connection parameters and their default-null fallback behavior are unexplained in both schema and description, leaving real ambiguity about scope.

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 (indexes of a collection) and what it returns (keys and options such as unique, sparse, TTL, partial filter), which cleanly distinguishes it from create_index and drop_index siblings. The verb is only implied by the noun phrase, but the intent to enumerate 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 call this versus alternatives (create_index, drop_index, collection_stats) and no prerequisites or conditions. The agent must infer that this is a read-only inspection step before index changes.

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 destructiveHint=false, so the description's marginal job is to add context. 'Forget' usefully signals that the stored profile is removed, not just the socket closed — but it says nothing about whether active operations are terminated, whether a missing profile errors, or whether the effect 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?

One short sentence, front-loaded with the action, with no filler. It is efficient but borders on under-specified rather than optimally concise.

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?

A state-changing tool on persistent configuration with one undocumented parameter and no output schema, yet the description covers neither the parameter's meaning nor error behavior for unknown names. The agent has to guess at the key details.

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 required parameter 'name' with 0% schema description coverage, and the description never mentions it or its format (profile name vs. host string). With full burden on the description for this gap, the single vague noun 'connection profile' does not compensate.

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 pair ('close and forget') and resource ('connection profile'), which is clear and differentiates it from add_connection and list_connections. It stops short of naming siblings, but the action 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?

No indication of when to use this instead of, say, simply not using a connection, nor any precondition such as whether the connection must be idle. The agent must infer the appropriate context entirely.

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 destructiveHint=false, so the bar is lower, but the description adds almost nothing beyond the name. It never explains the `drop_target` flag, which implies overwriting an existing collection, nor whether indexes, data, and metadata survive the rename.

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 tight sentence with no filler and the scope constraint front-loaded. It is efficient, but the terseness comes at the cost of the missing behavior detail rather than being deliberately minimal.

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 five-parameter mutation with no output schema and no annotation coverage of the drop_target risk, the description leaves the agent without enough to call it safely. Overwrite semantics and target-database selection are the key omissions.

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 five parameters, and the description only implicitly covers `collection` and `new_name`. The potentially destructive `drop_target` boolean and the `database`/`connection` targeting parameters go 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 (rename) and resource (collection) plus a scoping constraint ("within the same database"), which distinguishes it from create_collection and drop_collection. It does not name a sibling explicitly, but the action itself 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 guidance on when to rename versus creating a new collection and copying data, no prerequisites, and no warning about what happens if the new name already exists. The only hint is the implicit constraint that the rename cannot cross databases.

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 disclose readOnly=false, idempotent=false, destructive=false, openWorld=false. The description adds genuinely useful mutation semantics beyond that: only the FIRST matching document is affected and the replacement is a whole document. It still omits consequence details an agent needs for a write tool, e.g. what upsert=true does and whether non-matching filters fail silently.

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 sentence, front-loaded with the verb and resource, with the one qualifier that matters (first match) and the differentiating constraint in parentheses. No 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 mutation tool with no annotations covering safety, no output schema, and 0% parameter coverage, this is thin. The upsert flag is especially dangerous to leave unexplained on a replace operation, and there is no statement of return value or failure behavior.

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 6 parameters, so the description must compensate. It only indirectly illuminates filter and replacement, and says nothing about upsert, database, collection, or connection, leaving four parameters completely undocumented anywhere.

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 (Replace), resource (document), and scope (first match on filter), plus a parenthetical that implicitly separates it from update_documents by ruling out update operators. An agent can distinguish it from insert_documents and update_documents without opening the schemas, though the sibling is never named.

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 "no update operators" aside implies the choice against update_documents, but there is no explicit when-to-use/when-not guidance, no mention of what happens if multiple documents match, and no mention of the upsert flag's effect on tool selection.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is known. The description adds useful operational context (database resolution, admin requirement for server-level commands) but does not warn that arbitrary commands execute with full privileges, may drop data, or may create users with credentials — and it casually demonstrates a createUser with a password without noting the side effect.

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

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

A single dense paragraph with the core capability stated first, followed by examples and the database-defaulting note. The JSON examples are long but each illustrates a genuinely different command category, so they mostly earn their space.

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, high-risk catch-all with no output schema and no parameter descriptions in the schema, the description covers the essential mental model: this is db.runCommand, here is the command document shape, and here is how the database is resolved. Gaps remain around the 'connection' parameter, the shape of the returned result document, and error behavior, but the core call is adequately specified.

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% — properties carry only titles — so the description must carry the load. It does a good job on 'command' (format and examples) and 'database' (default behavior, 'admin' for server-level), but the third parameter 'connection' is never mentioned in the description or the schema, leaving one of three parameters fully 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 (run any database command, equivalent to db.runCommand) and grounds it with four concrete command examples. It implicitly positions itself as the generic escape hatch next to typed siblings like find, aggregate, and create_index, but never says so explicitly, so sibling differentiation is left to inference.

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 (serverStatus, usersInfo, createUser, collMod, explain) implicitly signal the class of operations this tool is for — administrative or unsupported-by-sibling commands — and the note about using 'admin' for server-level commands gives real routing context. However there is no explicit 'prefer find/aggregate/insert_documents when they apply' or any when-not-to-use guidance, which matters a lot for a catch-all tool.

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

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

Goes well beyond the annotations by disclosing rollback semantics ('nothing is written') and error behavior ('the error names the failing step'), plus the deployment topology requirement — none of which is in the structured data. One tension worth noting: the example op list includes 'delete'/'delete_many' while annotations declare destructiveHint=false; the transactional rollback rationale partly explains it, but the mismatch is not addressed.

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-loads the behavior in one sentence, then a short topology prerequisite, then an example. The example earns its space given the untyped parameter, though it is verbose relative to the prose.

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 mutation tool with no output schema and no field descriptions, the description covers the hard part (operation payload shape) and the operational preconditions. It does not say what a successful call returns (per-op results? counts?) or what database/connection default to when null.

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 0% and the operations parameter has no type at all, so the description must carry the load — and it does, giving concrete op shapes and enumerating the accepted op values (insert, update, insert_many, update_many, replace, delete, delete_many). The database and connection parameters are left completely unexplained, which is the remaining gap.

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 (execute several writes atomically) and names the distinguishing property — all-or-nothing semantics — that separates it from single-operation siblings like insert_documents and update_documents. An agent can route on this 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?

The atomicity framing plus the prerequisite 'Requires a replica set or sharded cluster' tells the agent when this tool is the right choice over the single-op write tools. There is no explicit when-not-to-use (e.g. 'use insert_documents for a single write'), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes by enumerating the returned data categories, which partly substitutes for the absent output schema, but it says nothing about cost, freshness, or how the optional connection affects scope.

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 zero filler; every item in the list corresponds to real returned data. It reads as a label fragment rather than a complete statement, which slightly weakens it but costs no clarity.

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

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

With no output schema, the field enumeration is necessary and is provided, and annotations cover the safety profile. However, the sole parameter is undocumented and there is no routing guidance among 28 siblings, leaving the definition adequate but not complete for an agent selecting and invoking it.

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, 'connection', with 0% schema description coverage, and the description never mentions it. An agent cannot tell from either source whether supplying a connection targets a specific server versus the default one, and for a single-parameter tool this gap is conspicuous rather than a baseline-4 case.

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 (server) and enumerates exactly what the summary contains: version, uptime, connections, operation counters, memory, replication role. That is more informative than a bare verb, but it never distinguishes this tool from close siblings such as current_ops or test_connection, so an agent has no explicit signal for choosing between them.

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 when-to-use guidance at all: nothing says to call this before diagnosing, or to prefer current_ops for active operations. The agent must infer usage purely from the field list, which is not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the shape of the result (version, edition, topology, auth user, transaction capability) in the absence of an output schema, though it says nothing about failure behavior when a connection is invalid.

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

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

A single dense sentence that front-loads the action and then enumerates the useful return fields with no filler or repetition.

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 does well to enumerate return content, but it leaves the sole input parameter entirely unexplained, which is the main thing an agent needs in order to actually invoke the tool correctly.

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

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

There is one parameter ('connection', nullable, default null) at 0% schema description coverage, and the description never mentions it. It does not clarify whether the value is a connection name from list_connections, a URI, or what a null default selects, so the agent must guess.

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 (connect) plus a detailed enumeration of what is returned: version, edition, topology, authenticated user, and transaction support. The resource and scope are unambiguous, but it never distinguishes itself from the sibling server_status, which plausibly overlaps.

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 tool name 'test_connection' and the diagnostic return payload; there is no explicit when-to-use statement, no mention of prerequisites, and no routing away from server_status at the point where an agent would most need it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is nominally covered. The description usefully adds the guardrail that an empty filter demands confirm_all=true and clarifies the single-document default, but says nothing about upsert side effects, array_filters behavior, or collation effects on matching.

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, front-loaded sentences with no filler; the accepted update syntax leads and the safety constraint trails. The first sentence is a fragment and the parenthetical examples are slightly dense, but nothing is wasted.

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

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

For a 10-parameter mutation tool with no output schema and zero schema descriptions, the description covers only the lowest-hanging semantics. Critical call-correctness details — upsert, array_filters, collation, and connection/database scoping — 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?

Schema coverage is 0% across 10 parameters, so the description carries the full burden. It only explains update (formats), many, filter (empty case), and confirm_all; database, connection, collection, upsert, collation, and array_filters remain completely undocumented anywhere.

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 operation (update) and immediately specifies the two accepted update forms — operator document with $set/$inc or an aggregation pipeline array — which is more precise than the bare tool name. It never names replace_document, so the agent must infer the boundary between partial update and full replacement.

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 selection rules for two parameters: many=false updates only the first match, and an empty filter requires confirm_all=true. It offers no guidance on when to prefer this over replace_document, upsert flows, or bulk multi-document updates.

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