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

Annotations only declare destructiveHint=false and idempotentHint=false; the description adds real behavioral context: it tests the connection before saving by default and persists to the configuration file. It also notes the placeholder-resolution mechanism, which affects how secrets are handled at runtime. It stops short of describing failure modes (e.g., what happens when the test fails or the name collides).

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 purpose is front-loaded in the first sentence, followed by parameter guidance in a logical order (url formats, engine inference, test/persist defaults). It is a single dense paragraph with some clause chaining, but no sentence is filler.

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

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

With an output schema present, return values need not be explained, and 100% schema coverage handles most of the ten parameters. The description covers the non-obvious semantics (url forms, engine inference, default test and persist) that an agent must know before calling. Minor gaps: access_mode's 'restricted' default and overwrite semantics are left entirely to the schema.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning beyond the schema: the accepted URI schemes (postgresql://, mongodb://, mongodb+srv://) and DSN form (host=... dbname=...), plus the rule that engine is inferred from the URL when omitted. Those are exactly the ambiguities an agent would otherwise have to guess at.

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 opening sentence "Adiciona uma conexão nomeada" gives a specific verb (add) and resource (named connection), which cleanly separates it from siblings like list_connections, remove_connection, and use_connection. It does not explicitly name the siblings or state the contrast, 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 context is implied by the name and by the note that the connection is saved to the config file, but the description never says when to choose this over use_connection or open_connection, nor what happens if the name already exists beyond the schema's overwrite flag. The one genuine guideline is the preference for ${VAR} placeholders over literal passwords, which is useful but narrow.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is to add context — and it does, by explaining what each check actually inspects (invalid/bloated indexes, transaction id wraparound, replication lag and slots, buffer cache hit rates). It still omits cost/duration expectations, which matters since 'all' runs eight checks, and says nothing about prerequisites such as privileges.

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?

Purpose leads, the check catalogue is a scannable bullet list where each line earns its place, and the selection/default rule closes the description. Slightly redundant in that the opening sentence restates the tool name almost verbatim, but the remainder is dense and well ordered.

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 readOnlyHint, an output schema, and 100% parameter description coverage, the description only needs to justify selection among checks — which it does thoroughly. Missing only runtime-cost/runtime-duration expectations so an agent can decide between one check and 'all' on a large database.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning beyond the schema's bare value list by defining what each health_type category detects — an agent can choose 'vacuum' for wraparound risk or 'replication' for lag without guessing. The connection parameter is left entirely to the schema, which is acceptable at full coverage.

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

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

States a specific verb and resource ("Analyzes database health") and immediately enumerates the eight check categories, which lets an agent distinguish it from siblings like analyze_workload_indexes, analyze_query_indexes, and get_top_queries that also touch database analysis.

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 how to select checks (single value, comma-separated list, or default 'all'), which is usage-relevant, but it never says when to prefer this diagnostic tool over the sibling analyzers, nor when a specific check subset is more appropriate than 'all'. Guidance is implied through the per-check explanations rather than stated.

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

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

readOnlyHint=true already tells the agent nothing is mutated, and the description adds that the output is a set of index recommendations rather than executed DDL, which is genuinely useful. It still omits engine/dialect assumptions, whether the analysis is against real statistics, and any cost or latency implications.

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 or repetition. It is efficient, though its brevity is achieved partly by omitting usage context rather than by tightening redundancy.

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

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

An output schema exists, so return values need not be explained, and readOnlyHint covers safety. However, for a tool with three parameters, an unfamiliar connection-resolution rule, and a near-identical sibling, the one-sentence description leaves the agent without enough to choose or configure 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 coverage is 100%, so baseline is 3, but the description adds a constraint the schema does not encode: the 'queries' array is capped at 10 entries. It says nothing about the behavior of 'connection' (fallback to active/default) or 'max_index_size_mb' beyond the schema, so it does not reach 5.

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 pair ('Analyze a list of SQL queries and recommend optimal indexes') with clear scope. It does not explicitly distinguish itself from the sibling analyze_workload_indexes, which is the nearest alternative, so the agent must infer the difference from names alone.

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 only guidance is the implicit 'up to 10' cap. There is no statement of when to prefer this over analyze_workload_indexes, nor any prerequisite (e.g., that queries must be valid for the connected engine, or that a connection must be selected first).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description needed to add context such as where the workload statistics come from, runtime cost, or required privileges. It adds only the vague notion of 'frequently executed queries' and says nothing about how expensive the analysis is or what it depends on.

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 efficient sentence with the action front-loaded and zero filler. It is short, though arguably too short given the gaps elsewhere.

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?

An output schema exists, so return values need not be explained. Still, for a workload-analysis tool the description omits the preconditions and cost of the analysis, leaving the agent without enough to judge when the call is appropriate.

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

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

Schema description coverage is 100%, so both connection and max_index_size_mb are documented in the schema, setting the baseline at 3. The description adds no meaning about how max_index_size_mb constrains the recommendations, so it earns no premium.

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: analyze frequently executed queries and recommend optimal indexes. However, it does not distinguish itself from the close sibling analyze_query_indexes (single-query analysis) or from get_top_queries, so an agent must infer the workload-vs-single-query split from the name alone.

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 'frequently executed queries' implies the workload-wide use case, but there is no explicit statement of when to pick this over analyze_query_indexes or get_top_queries, nor any prerequisites (e.g. query statistics needing to be enabled). Usage is only inferable.

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

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

With annotations only supplying readOnlyHint, the description adds genuinely useful behavioral context: the pool is freed server-side, the configuration is preserved, and the connection self-reopens on next use, which tells the agent the effect is cheap and reversible. The remaining tension is that freeing server-side connections is a runtime state change while readOnlyHint=true implies none, but the description's explicit 'reabre automaticamente' mitigates this rather than contradicting it outright.

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 its server-side effect, then the bulk flag, then the reversibility note. Nothing is padded, though the middle sentence largely restates the schema's close_all field.

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?

An output schema exists and both parameters are fully documented, so the description only needs to carry side-effect semantics, which it does well (config retained, auto-reconnect). It falls short of 5 only because it does not state what happens to in-flight queries or how this relates to remove_connection.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, so the description's mention of close_all=true adds no meaning beyond the field description. Baseline 3 applies since the schema does the heavy lifting for both close_all and connection.

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 ('Fecha o pool de uma conexão') plus the effect ('libera as conexões no servidor'), and the clause 'A configuração não é removida' implicitly distinguishes it from remove_connection. It does not name the sibling it is contrasted with, but the scope is unambiguous.

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

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

It gives one conditional usage rule ('Use close_all=true para fechar todas'), which covers the bulk-operation case. However, there is no guidance on when to prefer close_connection vs remove_connection or why one would close a pool at all, leaving most selection reasoning 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?

Beyond the destructiveHint annotation, the description discloses the key behavioral rule: restricted connections permit only reads, reject server-side JavaScript, and enforce a timeout, while unrestricted connections allow writes. It still does not mention truncation behavior, pagination, or result format, but annotations and the output schema cover part of that.

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 core action, followed immediately by the security constraint that governs which operations are valid. Every clause carries decision-relevant information with no filler.

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

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

Given the rich schema, existing output schema, and destructiveHint annotation, the description covers the most important missing context: which connections allow writes and which operations are read-only. It is nearly complete, though it could say more about result truncation and the destructive nature of write operations beyond what annotations imply.

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 all 17 parameters are already documented with examples and operational notes in the schema. The description adds contextual meaning to the operation parameter via the restricted/unrestricted constraint but does not otherwise elaborate on parameters. Baseline 3 is appropriate when the schema does the heavy lifting.

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 MongoDB operation on the chosen connection.' That clearly separates it from the SQL sibling execute_sql without naming it. The operation list itself is delegated to the schema rather than enumerated here, which keeps it from being a 5.

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

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

The description establishes an important usage constraint through the restricted vs unrestricted connection model. However, it never explicitly contrasts this tool with execute_sql or explain_query, nor does it state when to prefer a dedicated sibling. Usage is implied rather than directed.

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 supply only destructiveHint=true, and the description adds real substance beyond that: mode-dependent acceptance of DML/DDL, validation plus a READ ONLY transaction for restricted mode, and a timeout. It still doesn't say what happens with multiple statements, what an error response looks like, or that results beyond max_rows are silently truncated.

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 action front-loaded before the mode-dependent constraint. Every clause carries information the 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?

With an output schema present and the return shape covered there, the description only needs to convey execution semantics, which it does for the read-only/write split. It leaves gaps around statement count limits, error behavior, and truncation semantics for a tool whose annotation profile is a single destructiveHint.

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, and the description earns a bump by explaining what the 'connection' parameter actually implies — the connection's restricted/unrestricted mode determines whether the SQL is accepted. It adds nothing about 'sql' or 'max_rows' beyond the schema text.

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 first sentence states a specific verb and resource ('Execute SQL on the chosen connection'), which clearly separates it from execute_mongo and the connection-management siblings. It stops short of naming the nearest alternative (explain_query) or stating that this is the tool for actually running statements rather than inspecting plans.

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 conditional context — read-only SQL only on 'restricted' connections, any SQL on 'unrestricted' ones — which implies when a call will succeed. However, it never routes the agent to alternatives (explain_query for plans, list_connections to find a connection, execute_mongo for Mongo) or states prerequisites for picking a connection.

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

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

Annotations only declare readOnlyHint=true; the description restates the read-only framing but never discloses that analyze=True actually executes the query, which is a materially different (and potentially state-changing) behavior than the annotation implies. It also omits the runtime cost trade-off. The schema carries that caveat, but the description adds no behavioral context of its own.

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 front-loaded sentence with no filler; the grammar is slightly loose ("and provides detailed cost estimates") but every clause carries information.

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

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

An output schema exists, so return values needn't be described, and the parameter schema is thorough. However, for a tool whose analyze flag can actually run arbitrary SQL, the description should at minimum signal that execution mode exists and is slower/riskier.

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

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

Schema description coverage is 100%, with sql, analyze, connection, and hypothetical_indexes all documented in detail (including examples), so the baseline is 3. The description contributes nothing beyond the schema for any 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?

States a specific verb and resource ("Explains the execution plan for a SQL query") and adds what the output conveys (execution steps plus cost estimates). An agent can distinguish it from execute_sql or analyze_query_indexes without opening the schema, 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 guidance on when to call this versus execute_sql or the index-analysis siblings, and no warning about the significant difference between the estimate mode and analyze=True. Usage is only implied by the tool name.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely new context: the sampling-based inference and the explicit guarantee that "values are never returned", which matters for privacy expectations. It stops short of describing result size or sampling limits.

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

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

Two tight sentences, front-loaded with the general behavior and immediately narrowing to the MongoDB-specific return contents. Nothing is wasted or repeated.

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?

An output schema exists so return shape needn't be re-explained, and annotations cover read-only safety. The description covers the MongoDB path well but is silent on relational behavior (tables/views/sequences), leaving a small gap for non-MongoDB use.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the MongoDB remapping of schema_name and object_name. The description adds no parameter-level guidance beyond noting that object_type is ignored for MongoDB (which the schema also states).

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

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

States a specific verb and resource ("Show detailed information about a database object") and elaborates the MongoDB payload (collection type, count, indexes, inferred fields/types). This clearly distinguishes it from list_objects or execute_sql without naming siblings explicitly, so it stops short of a 5.

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

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

The phrase "detailed information" implies this is the follow-up to a listing call, but the description never states when to use it instead of list_objects, explain_query, or analyze_query_indexes, and offers no exclusions or 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does contribute one meaningful fact: results depend on the 'pg_stat_statements' extension being available, which signals a possible failure/empty-result mode. It says nothing about pagination, result shape, or what happens when the extension is missing.

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 core purpose is front-loaded. It is appropriately sized, though it is terse enough that it leaves the gaps noted in other dimensions unfilled.

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 an output schema present and annotations declaring read-only safety, the description needn't explain return values, and all three parameters are covered by the schema. Adding the extension dependency is genuinely useful; only minor items (behavior with a missing extension, relationship to explain_query) 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 description coverage is 100%, so every parameter (limit, sort_by, connection) is already documented in the schema. The description's phrase 'slowest or most resource-intensive' loosely mirrors the sort_by options but adds no syntax or behavioral detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Reports') and resource ('slowest or most resource-intensive queries') plus the data source ('pg_stat_statements'). This implicitly differentiates it from siblings like explain_query (single-query analysis) and analyze_workload_indexes (index advice), though it never names them explicitly.

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

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

Usage is only implied: an agent can infer this is a performance-triage tool for finding costly queries. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as explain_query for drilling into a specific statement.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one genuinely useful disclosure — that connection targets are shown without passwords ('destino sem senha') — plus pool status and active/default flags, but the rest is a field list whose behavior is already implied by the annotations and 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?

Two tight sentences with zero filler: the core behavior and returned attributes come first, the parameter guidance second. Nothing is repeated and each 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 single-parameter read-only list tool with an output schema, the description covers what it produces, the searchable fields, and the notable exclusion of passwords. Little an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by naming which fields 'search' matches against (nome, alias, tag, descrição), which the schema does not state. That is real added meaning for the only 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?

States a specific verb and resource ('Lista as conexões configuradas') and enumerates the attributes returned, so an agent knows exactly what comes back. It does not explicitly contrast itself with siblings like use_connection or reload_connections, but the verb+resource pairing is unambiguous enough to be selectable.

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 second sentence points the agent to the 'search' parameter for filtering by name, alias, tag or description, which implies the usage context. However, it gives no guidance on when to call this versus related siblings such as reload_connections or use_connection, leaving selection 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds only the MongoDB terminology mapping and nothing about return shape, object_type default behavior, or error cases (e.g., nonexistent 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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity borders on under-specification for a tool with multiple backend dialects.

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 an output schema present, return values need not be explained, and annotations cover safety. However, for a tool spanning SQL and MongoDB with an object_type filter that defaults to 'table', the description gives no guidance on choosing object_type or on behavior for a missing schema, leaving gaps an agent would face at call time.

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 three parameters (connection, object_type, schema_name) are documented in the schema itself, establishing the baseline of 3. The description's only added semantic is the MongoDB mapping, which duplicates what the schema's object_type and schema_name descriptions already say.

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 (objects in a schema), and the parenthetical clarifies what 'objects' means per backend. It is distinguishable from siblings like list_schemas and get_object_details, though it doesn't explicitly name 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, no mention of how this differs from list_schemas, and no indication of prerequisites or the alternative of get_object_details for inspecting a single object. The agent must infer usage purely from the tool name and sibling list.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description's only added behavioral value is the MongoDB/database equivalence note; it says nothing about permissions, result ordering, or size limits.

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

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

One short sentence with the core purpose front-loaded and a parenthetical dialect note appended. No filler or redundancy.

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

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

An output schema exists and annotations cover the safety profile, so return values and mutability need not be explained. What is missing is the relationship to list_objects and the fact that the connection argument can target a non-default database, which matters for a tool in a multi-connection server.

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 a single optional parameter with 100% schema description coverage, including its default and fallback behavior, so the schema fully carries parameter meaning. The description adds nothing about the connection parameter, which is acceptable at this coverage level.

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 pairs a specific verb (List) with a specific resource (all schemas in the database) and adds a dialect clarification that MongoDB returns databases. It is clear on its own, but it does not distinguish itself from the sibling list_objects, which an agent could easily confuse it with.

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 call that precedes list_objects/get_object_details, but the description never says when to prefer it or when to use list_objects instead. No prerequisites or exclusions 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?

Goes beyond the readOnlyHint annotation by disclosing that the pool is opened or reused (so repeat calls are cheap/idempotent) and that a connectivity test with latency is performed. It also names the returned fields. Minor gap: it does not mention what happens on failure (error vs. partial result) or that pool creation has a server-side cost.

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 dense sentence with the action front-loaded and the observable result trailing. No filler, though the description is written in Portuguese while the tool names and siblings are English, which is a minor consistency friction for matching.

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?

An output schema exists, so return values need not be spelled out, and the sole parameter is fully covered by the schema. What is missing is sibling routing (use_connection / close_connection) and error behavior, which matter for a connection-lifecycle tool in a crowded family.

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

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

Schema description coverage is 100% and the single optional 'connection' parameter already documents the alias and default fallback behavior. The description adds nothing further about the parameter, so the schema-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: opens/reuses the connection pool and tests it, returning database, user, version and latency. It does not distinguish itself from close_connection or use_connection, so an agent must infer the boundary, 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?

No guidance on when to call this versus use_connection or list_connections, and no prerequisites (e.g., must a connection exist first, or does omission fall back to the default?). The only routing hint, 'veja list_connections', lives in the schema property description, not the tool description.

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

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

Goes well beyond the readOnlyHint annotation by disclosing the concrete side effects: pools for unchanged connections stay open while pools for changed/removed connections are closed. That lifecycle detail is exactly the kind of behavior an agent cannot infer from the annotations and prevents surprise disruption.

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 result, then the side effects, then the caveat. 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 an output schema present, return values need not be explained, and the description already names the change categories returned. The auto-reload caveat and pool-handling semantics round out everything needed to invoke it 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?

The tool takes zero parameters, so the baseline is 4; the description correctly implies the call needs no input. Nothing further could be said about parameters here.

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 ('reloads the connections file now') and the observable effect (reports what changed: added/changed/removed/unchanged). This is clearly distinct from siblings like open_connection, close_connection or list_connections, so an agent can select it without reading 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?

Explicitly says when NOT to call it ('usually not necessary: the file reloads itself when it changes'), which is the key routing signal for a zero-parameter tool. It leaves the positive trigger slightly implicit (force a reload on demand rather than waiting for file-watch).

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

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

With destructiveHint=true already set, the description still adds real information: the pool is closed as a side effect, config-file-backed connections are erased from disk, and environment-defined connections are only dropped for this session. That is exactly the scope-of-destruction detail an agent needs before invoking a destructive tool.

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

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

One front-loaded sentence with a parenthetical for the conditional side effects; every clause adds a distinct fact (pool closed, file deleted, env-only session removal).

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?

An output schema exists and annotations flag destructiveness, so the description only needed to explain the mutation's scope, which it does thoroughly. The only gap is that it never contrasts with close_connection, leaving a plausible ambiguity for an agent choosing between them.

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 a single parameter and schema coverage is 100% ('Nome ou alias da conexão a remover'), so the schema already carries the semantics; the description adds nothing about accepted name vs. alias forms. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('remove a connection from the registry') and enumerates concrete effects: closes the pool and, when the connection came from the config file, deletes it there. That distinguishes it from list_connections and add_connection, but it never names close_connection, the sibling whose overlap (pool closing) most needs 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 parenthetical clarifies that env-var-based (.mcp.json) connections only leave the current session, which implies when removal is not persistent, but there is no explicit when-to-use vs. close_connection or reload_connections 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=true, so the safety profile is covered. The description adds genuinely new behavioural context that the call performs a validation and will fail if the connection cannot be opened, but it does not say what happens to a previously active connection, whether the setting persists across requests, or what failure looks like.

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 in which both clauses earn their place, and the primary effect (defining the active connection) is front-loaded. It is written in Portuguese while sibling tooling and annotations are English, a minor consistency cost.

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 an output schema present, return values need not be explained, and the validation behaviour is disclosed. However, for a tool that mutates session state among many connection-management siblings, the description still leaves the agent guessing about failure handling and about how it relates to open_connection.

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

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

Schema coverage is 100% and the single param already documents 'Nome ou alias da conexão'. The description adds the key semantic that the argument becomes the session-wide default used whenever 'connection' is omitted elsewhere, which the schema does not convey.

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: it sets the session's active connection and verifies it can be opened. This is distinguishable from open_connection/close_connection in intent, though the description never names those siblings, so the boundary with open_connection (which presumably also opens a connection) 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 parenthetical 'usada quando connection é omitido' implies when the setting matters, but only for other tools' behaviour, not for when to call this tool instead of open_connection or add_connection. No exclusions or alternatives are given.

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