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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing that $out and $merge stages are recursively rejected and that a result limit is appended, which tells an agent exactly how write-capable pipelines will be neutralized.

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 tight sentences with zero waste. The core operation is front-loaded and the follow-up sentence supplies the most decision-relevant behavioral caveat.

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

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

With no output schema and 0% schema description coverage, the description should compensate for the parameter gap but does not. It covers the safety/behavior story well, leaving callers to guess the meaning of most parameters.

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 (2 required), so the description carries the full burden. The only hint is "appends a result limit," which loosely relates to the limit parameter; pipeline syntax, connection_id, timeout_ms, and response_format are entirely 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: "Run a bounded read-only MongoDB aggregation." It is clear and accurate, but it never distinguishes this tool from the close sibling mongo_find, so an agent must infer when aggregation is warranted over a simple find.

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 word "aggregation" and the "bounded read-only" framing. There is no explicit when-to-use statement, no comparison to mongo_find, and no note about prerequisites such as a valid connection_id.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description reinforces read-only status and adds a useful 'bounded max execution time' note. However, it doesn't say what happens when the time bound is exceeded or what auth scope is needed, so it goes only modestly beyond the annotations.

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

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

Two tight sentences with no waste, front-loading the core action before the safety note. Nothing is padded or redundant.

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

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

With 5 parameters, 0% schema coverage, and no output schema, the description is thin: it omits the required connection_id/collection semantics, the response_format enum, and any return-value characterization. Annotations cover the safety profile, but the parameter story is incomplete.

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 5 parameters, so the description carries the full burden. It only hints at the filter and timeout (via 'matching a MongoDB filter' and 'bounded max execution time'), leaving connection_id, collection, and response_format 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 precise verb+resource: counting documents matching a MongoDB filter. Clear what the tool returns, but it never distinguishes itself from siblings like mongo_find or mongo_aggregate, which an agent must choose between.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives such as mongo_find. Nothing tells the agent why it would count rather than fetch or aggregate.

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=true, so the safety profile is known. The description adds genuinely new behavioral context beyond the structured data: the environment gate (non-production only, production always blocked) and the allow_all precondition for empty filters. Auth requirements and return behavior remain unstated.

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 tight sentences: the action is front-loaded, then the two gating constraints follow. No filler, no repetition of the title or annotations.

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 0% schema coverage and no output schema, the description covers the critical safety rules but omits what the operation returns (count of deleted documents?) and the meaning of connection_id/collection/response_format. Adequate for a guarded delete, but not fully self-contained.

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 5 parameters, so the description carries the burden. It clarifies the filter/allow_all interaction, which is real semantic value, but leaves collection, connection_id, and the response_format enum undocumented. Partial compensation only.

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 ('Delete matching documents') and adds a scope qualifier ('from a non-production collection') that inherently separates it from mongo_find, mongo_update_many and mongo_insert_one. Sibling tools are not named explicitly, but the verb and environment restriction make the intent 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?

Provides two concrete operational rules: empty filters require allow_all=true, and production is always blocked, telling the agent when the call will be refused. It lacks explicit guidance pointing to alternatives (e.g. mongo_update_many when the intent is modification), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered; "read-only in every environment" is largely a restatement of that. The word "bounded" hints at enforced limits but the description never says what they are (max limit 200, default 50, timeout ceiling 120s), and it omits any note on cost, auth, or rate limits. Modest added value over the annotations.

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

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

Two tight sentences with zero filler; the core operation and its controls are front-loaded, and the safety statement closes it out. Nothing needs to be trimmed or reordered.

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 9-parameter tool with nested free-form objects and no output schema, the description is thin: it never explains how filter/sort/projection documents should be shaped, omits response_format (which changes the return), and leaves connection_id/collection semantics to the schema. It is adequate but leaves real gaps an agent would hit in practice.

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 9 parameters, so the description carries the burden and does name five of the nine (filter, projection, sort, skip, max-time/timeout_ms), which is meaningful. However, it gives no syntax or shape guidance for the free-form filter/sort/projection objects, no mention of limit, connection_id, collection, or response_format, and no defaults or bounds.

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 a bounded MongoDB find query") and enumerates the query knobs, which cleanly separates it from siblings like mongo_aggregate and mongo_count_documents. An agent can identify the tool's job without opening the schema.

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

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

There is no explicit when-to-use guidance or routing to alternatives. The agent must infer from the name that this is the document-retrieval tool versus mongo_count_documents or mongo_aggregate, and nothing states prerequisites (e.g., a valid connection_id from mongo_list_connections) or when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write/non-destructive profile is covered. The description adds a genuine operational constraint beyond the annotations: inserts only succeed on non-production connections, and production is read-only. It omits error semantics such as duplicate-_id 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 short sentences with zero filler, and the critical scoping constraint (non-production only) is stated up front rather than buried. Nothing in the text is redundant with the title or restates the name.

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 mutating tool with no output schema, 0% parameter description coverage, and nested document input, the description covers only the environment restriction. It says nothing about return content, duplicate-key/error behavior, or the meaning of response_format, leaving real gaps an agent would need before calling 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 carries the full burden and largely fails it. 'Document' and 'collection' are mentioned only incidentally in prose, and nothing explains connection_id or the response_format enum. The agent gets no format, constraint, or default guidance beyond what it must infer from the schema names.

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

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

The description states a specific verb+resource combination ('Insert one document into a ... MongoDB collection') and scopes it to non-production collections, which separates it from read tools like mongo_find and bulk mutators like mongo_update_many/mongo_delete_many. It stops short of explicitly naming the sibling tools it is distinct from, but the operation is unambiguous.

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

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

The statement that production connections are always read-only effectively tells the agent when this tool will not work, which is useful implied guidance. However, no alternatives are offered (e.g., what to use to modify existing documents), and there is no explicit when-to-use framing beyond the environment restriction.

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 useful context that results are bounded and the name filter is case-insensitive, but says nothing about pagination, ordering, or what happens at the limit boundary.

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. It packs the resource, the bounded-size behavior, and the filter into one efficient statement.

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 list tool with annotations covering safety and no output schema, the description is largely sufficient. Minor gaps around return format and connection context are low risk given the self-explanatory 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%, so the description must compensate. It partially does by describing the limit as a 'bounded result size' and name_contains as a 'case-insensitive name filter,' but leaves connection_id and response_format (an enum with default) 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?

States a clear verb+resource ('List MongoDB collections and metadata') and adds scope via 'bounded result size' and 'optional case-insensitive name filter.' It is distinct from siblings like mongo_list_connections, though it never names that sibling to sharpen the distinction.

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 mongo_list_connections or mongo_find. Usage is only implied by the verb 'List,' with no preconditions, exclusions, or named alternatives.

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 a genuinely useful trait annotations cannot express: that URIs and credentials are never returned, defining the data-exposure boundary of the response.

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, zero filler, with the returned-field list front-loaded before the security caveat. Every clause earns its place.

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

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

There is no output schema, and the description compensates by enumerating the returned fields. For a parameterless read-only listing tool this is nearly sufficient; only pagination/ordering behavior is unaddressed.

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

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

Schema description coverage is 0%, but the sole parameter (response_format) has an enum of two self-explanatory values and a documented default, so little is actually ambiguous. The description adds no meaning beyond the schema, but the gap it leaves is trivial.

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 connections) and even enumerates the fields returned (IDs, environments, databases, access modes). It is clearly distinct from the mysql_* and redis_* siblings by resource, but never names an alternative, so cross-sibling routing is left implicit.

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 no when-to-use, when-not-to-use, or prerequisite context — nothing tells the agent to call this before mongo_find/mongo_aggregate to discover valid connection IDs. Usage is only inferable from 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation risk is covered. The description adds genuinely new guardrail context beyond the annotations: the allow_all escape hatch for empty filters and the hard production block. It omits any statement of scope of effect or return 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 short sentences, zero filler, with the collection scope and the safety preconditions front-loaded.

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

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

For a destructive, 6-parameter mutation with 0% schema coverage and no output schema, the description covers the critical safety guardrails but leaves most parameters and the return/response_format behavior undocumented. It is adequate on risk, thin on mechanics.

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, yet it only explains 'filter' (in the empty-filter case) and 'allow_all' with a real precondition. The update document, collection, connection_id, and response_format parameters are left 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+resource ('Update matching documents') plus a scoping qualifier ('in a non-production collection'), which cleanly separates it from siblings like mongo_delete_many, mongo_insert_one, and mongo_find.

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

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

Gives clear conditional guidance: empty filters require allow_all=true and production is always blocked, so the agent knows when the call will be rejected. It stops short of naming alternative tools for out-of-scope cases (e.g., what to use against production), so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description reinforces this with 'read-only in every environment', which adds the environment-wide scope. Since no output schema exists, the enumeration of returned content (types, nullability, defaults, comments, ordered index columns) is genuinely additive behavioral context.

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

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

Three short sentences, zero filler, with the scope constraint front-loaded and the return payload and safety profile following in priority order. Every sentence earns its place.

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

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

For a simple, read-only introspection tool with full schema coverage, the description covers scope, return contents, and safety. With no output schema it adequately compensates by naming the returned fields; only the absence of an explicit usage condition against sibling tools keeps it from being fully complete.

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

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

Schema description coverage is 100%, so all four parameters, including the schema default and the response_format enum, are already documented in the schema. The description only reinforces 'one exact table' exactness and adds no syntax, naming, or format guidance beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Inspect columns and indexes for one exact MySQL table or view') and scopes it to a single exact table, which cleanly separates it from mysql_list_tables (enumeration) and mysql_query (data retrieval). An agent can select it 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 phrase 'one exact MySQL table or view' implies you must already know the table name and that this is a pre-query schema-inspection step, but usage is only implied. There is no explicit when-to-use statement, no mention of when to prefer mysql_query or mysql_list_tables, and no stated prerequisites.

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

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

Annotations already declare destructive/non-idempotent/openWorld, but the description adds context the annotations cannot convey: production connections are hard-rejected, only one statement may be submitted, and DDL may implicitly commit and not roll back. These are genuine operational constraints beyond the structured hints.

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

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

Three short sentences with zero filler, front-loaded with what the tool does, then the scoping constraint, then the sibling routing. Every clause carries information an agent needs.

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

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

For a destructive DDL/DML tool with rich annotations and full schema coverage, the description covers safety constraints, statement cardinality, and alternatives. It omits any indication of what a successful execution returns or how errors surface, which is a minor gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic linkage by stressing 'parameterized' (pointing at the positional parameters array) and the single-statement restriction on sql, and by implying why DDL needs separate handling (allow_ddl). It stops short of documenting allow_all, timeout_ms, or response_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 and resource (execute one parameterized DML or DDL statement) and scopes it to a non-production connection. It explicitly differentiates itself from mysql_execute_transaction in the same description, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit when-to-use routing: single statements here, multi-statement atomic DML via mysql_execute_transaction, and DDL run separately. It also states the negative condition (never against a prod connection). This is explicit when/when-not/alternative 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 cover the safety profile (destructive, non-idempotent, non-read-only), but the description adds genuinely extra behavior: atomic execution with rollback on the first error, enforcement that the target is non-production, and the explicit rejection list. These are runtime semantics an agent cannot derive from the annotations or schema, so the description earns its keep.

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 tightly written sentences, front-loaded with the core action and followed immediately by the failure semantics and the exclusion list. No filler, and the most decision-relevant facts (atomicity, non-prod, rejections) come first.

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

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

For a destructive multi-statement mutation with no output schema, the description supplies the essentials: atomicity, rollback behavior, statement limits, and the environment/statement-type restrictions. It stops short of describing what a successful call returns (e.g. affected-row counts or per-statement results), which an agent might want, though response_format hints at rendering options.

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

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

Schema coverage is 100%, so every parameter (connection_id, statements, timeout_ms, response_format, allow_all) is already documented in the schema, including the 1-20 bound and the ? placeholder convention. The description's mention of 'parameterized' and the statement count adds only marginal meaning over the schema, so the baseline 3 applies.

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

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

States a specific verb (atomically execute) with the resource (parameterized INSERT/REPLACE/UPDATE/DELETE statements), a scope bound (1-20), and a hard constraint (one non-production connection). It implicitly separates itself from the read-oriented sibling mysql_query by naming 'reads ... rejected', but it never names an alternative tool the way a fully differentiated definition would.

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

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

Gives clear when-not-to-use conditions: prod, DDL, reads, transaction control, and session control are all rejected, which lets an agent route those cases away without trial and error. It falls short of 5 because it never points to the correct alternative (e.g. mysql_query for reads, plain mysql_execute for single statements), leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: 'Passwords are never returned,' which tells the agent the connection secrets are redacted and it can safely surface this output to the user.

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, zero waste: what is returned first, the security guarantee second, the usage trigger third. Front-loaded and scannable.

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-required-param read-only discovery tool with no output schema, the description covers what the tool returns, what it withholds (passwords), and when to call it. Nothing needed to invoke it correctly is missing.

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

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

There is one optional parameter (response_format) and schema description coverage is 100%, so the schema fully documents the enum and its meaning. The description adds nothing about rendering format, which is acceptable given the schema does the work — the baseline 3 applies when coverage is high.

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 (MySQL connections), and enumerates the payload returned: connection IDs, environments, databases, and effective access modes. The 'MySQL' qualifier plus the connection-registry framing cleanly separates it from the sibling mongo_list_connections and redis_list_connections.

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

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

'Use this before other tools when the connection ID is unknown' gives an explicit precondition and a discovery role relative to every other mysql_* tool. It stops short of a when-not clause (e.g., what to do when the ID is already known), so it is clear context rather than full routing 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 'read-only in every environment' largely restates structured data. The description does add non-redundant value by naming the returned fields (type, engine, row estimate, storage size) in the absence of an output schema; pagination is mentioned but its behavior (defaults, max page size) is left to the 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?

Three sentences, front-loaded with the verb and scope, then return fields, then the safety note. No wasted clauses. The read-only sentence duplicates the annotations, costing it the top score, but it is short and clearly separated.

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 usefully enumerates the returned columns, which is exactly what an agent cannot learn elsewhere. Read-only status, filtering and pagination are all signalled. Remaining gaps are minor: no guidance on empty results, no addressing of the openWorldHint (multiple configured connections), and no cross-reference to sibling tools.

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 67%, so baseline is 3. The description says 'pagination' and 'optional name filter', which maps to limit/offset/name_contains, but adds no semantics beyond what the schema already documents (case-insensitive substring, schema defaulting to the configured database). It provides no detail for the undescribed limit/offset bounds.

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

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

States a specific verb and resource ('List tables and views in a MySQL schema') plus scope modifiers (pagination, name filter). An agent can tell this apart from mysql_query or mysql_describe_table by resource, but the description never names a sibling or the boundary between them, 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?

Usage is implied by the resource: enumerate tables/views in a schema, optionally narrowed by name_contains. There is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as mysql_describe_table for column detail or mysql_query for row data, so routing 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?

Annotations cover the safety profile (readOnlyHint, idempotentHint, destructiveHint), but the description adds substantial non-obvious behavior: the exact rejection list (writes, locking reads, file access, session mutation, multiple statements, resource-exhaustion functions), the read-only transaction wrapping, and the returned-data cap. This is exactly the kind of enforcement detail an agent cannot get from annotations alone.

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 core action and immediately followed by the enforcement scope. No filler and no repetition of the title.

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

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

For a complex SQL-execution tool with no output schema, the description covers the critical constraints (single statement, read-only, rejection list, data cap) that an agent needs to call it correctly. Minor gaps remain: error/failure behavior and the practical meaning of 'caps returned data' beyond max_rows are not spelled out.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including placeholder usage and limits. The description's mention of 'parameterized' and 'caps returned data' adds little beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Run exactly one parameterized read-only MySQL statement') with a clear read-only scope qualifier. Sibling tools like mysql_execute are not named, so the agent must infer the read-only vs. write distinction rather than being routed 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?

The description establishes context ('Works in every environment, including prod') and implicitly carves out a safe-use niche via the read-only framing. However, it never states when to choose this over mysql_execute or mysql_execute_transaction, so usage is implied rather than guided.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real value beyond them by disclosing the explicit allowlist posture and enumerating what is rejected (KEYS, scripting, pub/sub, transactions, blocking, mutations) — constraints an agent cannot derive from the annotations or 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?

Two sentences, zero filler, and the primary constraint (read-only, allowlisted) is front-loaded before the rejection list. Nothing could be cut without losing information.

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

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

There is no output schema, yet the description never explains what the command returns or how the allowlist is discovered, which matters for a tool that accepts arbitrary command names. Safety is well covered by annotations and the rejection list, but the 'what is actually allowed' gap is a meaningful omission for an agent.

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 only 33% (connection_id and response_format are undocumented), so the description must carry more weight. It clarifies that arguments are tokenized rather than a shell string, but that nuance is already present in the schema's own argument description, and it says nothing about connection_id or response_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 ('Run one ... read-only Redis command') with clear scope qualifiers: allowlisted, tokenized arguments. However, it does not distinguish itself from the sibling redis_execute, which is presumably the write-capable counterpart, so the agent must infer the boundary.

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 rejection list (KEYS, scripting, administration, pub/sub, transactions, blocking, mutations) implies when this tool is appropriate, and it is genuinely useful routing info. But it never names an alternative for the rejected categories (e.g. redis_execute) or states a positive condition for choosing this tool over redis_scan_keys.

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 idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: only allowlisted mutations run, the connection must be non-production, and specific command classes are refused. It still doesn't say what gets destroyed on success, whether failures leave partial state, or how errors surface.

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, zero filler, with the core capability and the hard safety scoping front-loaded. Every clause earns its place by either defining the action or eliminating errant uses.

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, open-world mutation tool with annotations covering the safety profile and no output schema, the description supplies the critical constraints (non-production only, allowlist only, rejections). The remaining gap is operational setup: how an agent obtains a valid connection_id via the sibling list tool.

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

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

Schema coverage is only 33%, with connection_id (required) and response_format carrying no descriptions. The description's 'Execute one ... command' constrains the arguments parameter to a single allowlisted command rather than a pipeline, which is useful, but it says nothing about where connection_id comes from or what response_format controls, so 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 (Execute), resource (Redis command), and narrows scope to a single allowlisted mutation on a non-production connection. The rejection list (production, scripts, transactions, admin, pub/sub, flush, arbitrary) makes it clearly distinguishable from a general redis_command 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?

Explicit when-not conditions: production connections, scripts, transactions, administration, pub/sub, flush, and arbitrary commands are all rejected. What's missing is naming the alternative tool to use (e.g., redis_command for reads or redis_list_connections to obtain a connection), so the routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: the exact returned field set and the security guarantee that passwords are never returned. It stops short of covering auth requirements or any rate/size limits, so not a 5.

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

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

Two short sentences with no filler, and the substantive content (what is listed) is front-loaded ahead of the security caveat. Every sentence earns its place.

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

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

With no output schema, the description usefully names the returned fields and the password-exclusion guarantee, and annotations carry the safety profile. It is nearly complete for a simple read-only list tool; only the response_format parameter and any pagination/size expectations are left unaddressed.

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

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

The single parameter response_format has 0% schema description coverage and is never mentioned in the description. The enum values (markdown/json) are self-explanatory, but with zero coverage the description should have compensated and does not, leaving the output-format choice undocumented in prose.

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) plus resource (Redis connections) and enumerates exactly what is returned: connection IDs, environments, logical databases, and access modes. This is enough to distinguish it from redis_scan_keys, redis_command, and the mysql/mongo connection listers without opening any schema.

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

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

There is no when-to-use or when-not-to-use statement, and no mention of the sibling tools that consume these connection IDs (redis_command, redis_execute). The discovery role is only weakly implied by the phrase 'connection IDs'; no context or exclusions are given.

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

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

Annotations already declare readOnly, non-destructive, open-world, and non-idempotent. The description adds real behavior beyond them: the scan is incremental and non-blocking, and it returns a cursor plus a bounded page, which explains pagination semantics an agent must handle. It omits rate limiting or auth context, so not a 5.

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

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

Two tight sentences with the mechanism and the distinguishing non-blocking property front-loaded, and the return shape stated second. No filler or restatement of the title.

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

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

For a six-parameter tool with no output schema and no parameter descriptions, the description is only partially sufficient: it conveys the core concept and the pagination model but leaves parameter meanings and alternative selection unaddressed. Annotations cover the safety profile, which lifts it above inadequate.

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 six parameters, so the description carries the burden and largely fails. It references the returned cursor and a bounded page (loosely mapping to cursor and count) but says nothing about pattern matching, type filtering, response_format, or connection_id, leaving most parameters undefined in both schema and prose.

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 (scan) and resource (Redis keys) and immediately differentiates the mechanism from the blocking KEYS command, which helps separate it from the raw redis_command sibling. It does not explicitly name an alternative tool by name, 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?

Implied usage only: the agent can infer this is for enumerating keys non-blockingly, and the 'without using the blocking KEYS command' clause hints at when it is preferable. However, it never states when to use this versus redis_command or redis_execute, nor any prerequisites such as a valid connection_id.

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