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

With no annotations, the description carries the burden of disclosure. It adds a useful side-effect detail: removal of 'cached metadata.' However, it does not mention irreversibility, failure behavior, or prerequisites. While it discloses what gets destroyed, it stops short of a full behavioral picture.

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

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

The description is a single, concise sentence that immediately conveys the core action and scope. Every word adds value, with no filler or redundancy. It is ideally sized for quick comprehension.

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

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

For a simple one-parameter deletion tool, the description covers the primary function and a key side effect. However, it omits warning about permanence and error cases, which are important contextual details. An output schema exists, so return values are covered, but the description still feels incomplete for a destructive operation.

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

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

The single parameter, document_id, is only described in the schema as a string. The description does not explain what a document_id looks like, how to obtain it, or any format requirements. Given 0% schema description coverage, the description should compensate but does not, leaving the parameter under-specified.

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

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

The description clearly states the action ('Remove') and the resource ('one document from the vector store and its cached metadata'). It is specific and distinct from sibling tools like search_documents or list_indexed_documents, which focus on retrieval. No ambiguity about what the tool does.

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 is provided on when to use this tool versus alternatives, such as refresh_document_index or other document tools. The description implies deletion usage but does not explicitly state exclusions or recommended contexts, leaving the agent without clear decision support.

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

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

The description mentions 'cached table,' which hints at a read-from-cache behavior, but it does not explain what happens if the table is not cached, whether any refresh occurs, or any error conditions. With no annotations, the description bears the transparency burden and only partially meets it.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently communicates the core purpose without 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?

Despite having an output schema, the description is minimal for a tool with three required parameters and no annotations. It lacks usage context, parameter semantics, and behavioral edge cases, making it incomplete for an agent to invoke correctly in all situations.

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

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

Schema description coverage is 0%, and the description does not elaborate on any of the three required parameters (connection_id, schema, table). It adds no meaning beyond the bare property names and constraints already present in the input schema.

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

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

The description uses a specific verb ('Return') and identifies the resource ('columns, keys and comments') and scope ('one cached table'). It clearly distinguishes this tool from siblings like list_tables and search_catalog by focusing on table schema metadata.

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 is provided on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or alternative tools, leaving the agent to infer usage context.

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

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

With no annotations provided, the description carries the full burden. It mentions 'validated' and 'same limits as find()' but does not disclose whether the pipeline may write (e.g., $out/$merge), what 'validated' means, or any error/limit specifics. This is insufficient for a tool with potential side effects.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, making it appropriately sized for the tool's scope.

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?

While an output schema exists, preventing the need to explain returns, the description omits critical context for a 5-parameter tool: when to use it, what 'validated' implies, relationship to sibling tools, and potential write behavior. This makes it incomplete for safe invocation.

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

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

Schema description coverage is 0%, so the description needed to compensate by explaining parameters. It does not mention connection_id, collection, pipeline, max_rows, or timeout_seconds at all. Even though parameter names are somewhat self-explanatory, the description adds no semantic value for their correct usage.

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

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

The description clearly states the verb 'Execute' and the resource 'validated aggregation pipeline', distinguishing it from sibling tools like execute_mongo_find. The reference to 'same limits as find()' further clarifies its scope within the MongoDB tool family.

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

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

The description implies usage for aggregation pipelines and references find() limits, offering some context. However, it does not explicitly state when to prefer this over execute_mongo_find or validate_mongo_query, nor does it mention any 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?

The description adds 'validated' and mentions limits, which provides some behavior context. However, with no annotations, it fails to disclose error handling, read-only nature, or prerequisite connection state, leaving transparency gaps.

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

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

The description is a single, front-loaded sentence with no redundant wording. Every element contributes to the core purpose and constraints.

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?

While an output schema exists, the tool has no annotations and the description is too sparse for a 6-parameter operation. It omits parameter semantics and behavioral details, making it under-specified for reliable agent invocation.

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

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

Schema description coverage is 0% and the description provides no information about parameters beyond the schema. It does not explain filter structure, defaults, or how limits interact, offering no added meaning for the six parameters.

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

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

The description clearly states the tool executes a MongoDB find() operation, using the specific verb 'Execute' and resource 'find()'. It is distinct from siblings like execute_mongo_aggregate and validate_mongo_query, making the purpose 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 mention of row, byte, timeout, and concurrency limits implies controlled execution, but it does not explicitly state when to use this tool over alternatives or when not to use it. Sibling tools like execute_mongo_aggregate suggest a different scope, but the description lacks direct guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses the query is validated and executed under row, byte, timeout, and concurrency limits, providing some behavioral context. However, it does not explicitly state read-only nature (though SELECT implies it), describe behavior when limits are exceeded, or mention connection prerequisites.

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

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

The description is a single sentence, front-loaded with the action 'Execute', and contains no filler or redundant information. Every word adds value.

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?

Although an output schema exists and return values are covered, the description lacks important context such as the need for an existing connection (implied by required connection_id), the meaning of 'validated' (whether pre-validation via validate_sql is required), and the exact consequence of concurrency limits. Given the tool's complexity and sibling tools, more context would improve usability.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only hints at 'limits' which loosely maps to max_rows and timeout_seconds, but leaves connection_id, parameters, and the validation requirement for sql unexplained. This is insufficient for an agent to understand how to set each parameter effectively.

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

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

The description uses a specific verb 'Execute' and names the resource as 'one validated SELECT', clearly indicating a read-only SQL query operation. It distinguishes itself from siblings such as execute_mongo_find (MongoDB) and generate_and_execute_query (generating plus executing).

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

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

The description implies usage for executing SELECT statements and mentions limits, but it does not explicitly state when to use this tool versus alternatives like explain_query or generate_sql. No when-not-to-use guidance is provided.

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

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

With no annotations, the description carries the burden. It discloses the 'cached' nature and that it uses the real SQL definition, which adds some behavioral context. However, it doesn't clarify cache semantics, error behavior, or whether this is a read-only operation beyond what 'explain' implies.

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

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

The description is a single, concise sentence that front-loads the core action and resource. No wasted words 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?

Given the presence of an output schema, the description need not explain return values. However, it omits details about caching implications, whether the object must exist, or fallback behavior. It is sufficient for a basic understanding but lacks edge-case context.

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

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

Schema description coverage is 0%, and the description does not explain parameters. The phrase 'procedure or trigger' hints at the object_type enum, but connection_id, schema, name, and table are not elaborated. The schema itself is self-explanatory, but the description adds little value beyond it.

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

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

The description clearly states the tool explains one cached procedure or trigger from its real SQL definition. The verb 'explain' is specific to retrieving the definition, and it distinguishes from siblings like list_procedures (listing) and explain_query (query 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?

No explicit guidance on when to use this tool versus alternatives is provided. The description implies a use case (getting a procedure/trigger definition) but does not mention prerequisites, exclusions, or sibling tools like list_procedures or describe_table.

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

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

With no annotations, the description carries full responsibility for disclosing behavior. It notes that ANALYZE is not used, implying the query is not executed, but it does not explicitly state that the operation is read-only or side-effect-free. It also does not mention any permissions, rate limits, or prerequisites, leaving the agent to infer safety and 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?

The description is a single sentence that is directly on point, with no filler or redundant information. It front-loads the core purpose and is appropriately sized for the tool's simplicity.

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?

Despite having an output schema, the description offers minimal context for a tool with four parameters and no annotations. It does not clarify the meaning of the JSON plan, parameter usage, or when to select this tool over related siblings. The description is too sparse for the tool's complexity, leaving significant gaps in guidance.

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 schema has 0% description coverage, and the description does not compensate by explaining any of the four parameters (sql, parameters, connection_id, timeout_seconds). The agent is left with no understanding of what each parameter means, how they interrelate, or what formats are expected beyond raw schema types.

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

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

The description clearly states the tool returns a JSON PostgreSQL plan for a SELECT query without executing it, which distinguishes it from siblings like execute_read_query and validate_sql. It uses a specific verb ('Return') and resource ('PostgreSQL plan for a SELECT'), leaving no ambiguity about its core function.

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 provides no explicit guidance on when to use this tool versus alternatives. It only scopes the tool to SELECT queries, but does not mention when a plan is needed, what to do for non-SELECT statements, or how this compares to validate_sql or execute_read_query. No exclusion criteria or alternative tools are referenced.

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

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

With no annotations, the description must carry the full burden. It discloses conditional execution and 'full revalidation' but leaves critical behaviors unspecified, such as whether writes are allowed, what revalidation entails, or failure behavior. This is insufficient for a potentially mutating query execution 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?

The description is a single concise sentence, front-loaded with the core action. Every word earns its place; there is no fluff 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?

Given the tool's complexity (generation + conditional execution), the presence of sibling tools, and the lack of annotations, the description is too sparse. It omits usage context, side-effect transparency, and parameter semantics, though the output schema reduces the need to describe return values.

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

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

Schema description coverage is 0%, and the description provides no parameter details. Though parameter names like connection_id, max_rows, and timeout_seconds are self-explanatory, the description adds no meaning about how they interact with query generation or execution.

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?

Description clearly states the tool generates SQL and executes it conditionally, which distinguishes it from siblings like generate_sql and execute_read_query. However, it doesn't explicitly mention that the SQL is generated from the 'question' parameter, though this is implied.

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 is provided on when to use this tool versus alternatives such as generate_sql, validate_sql, or execute_read_query. The conditional 'only if it is executable' is a behavioral condition, not a usage guideline.

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

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

With no annotations, the description must fully disclose behavioral traits. It mentions 'full revalidation' as a safety mechanism but does not explain whether the query is read-only, what permissions are needed, or what side effects execution may have. 'Export inline' is also undefined, leaving significant gaps about the tool's 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?

The description is a single sentence with no filler, efficiently conveying a three-step process. However, it is under-specified for a tool with four parameters and no annotations, which is more under-specification than conciseness. It is concise but at the cost of necessary detail.

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

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

The tool has four parameters, no annotations, and low schema coverage. While an output schema exists, the description omits critical details like the meaning of 'full revalidation', how exporting works, parameter roles, and any constraints. This is insufficient for an agent to use the tool 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 only 25% (only format has a description). The description does not mention connection_id, question, max_rows, or format, and adds no semantics beyond the schema. With such low coverage, the agent must guess how to populate these fields correctly.

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 clear pipeline: generate SQL, execute it with revalidation, and export inline. This is a specific verb+resource combination, and the revalidation step helps distinguish it from simpler query tools. However, 'export it inline' is somewhat ambiguous and the report aspect is only implied by the tool name.

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 is provided on when to use this tool over siblings like generate_and_execute_query or execute_read_query. There are no conditions, exclusions, or alternative tool references, leaving the agent to infer usage from the tool name and 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?

With no annotations, the description carries the transparency burden. It discloses the key non-execution behavior, but does not mention other behavioral aspects such as validation failure handling, whether the SQL is returned as a string, or permission/rate-limit concerns. The existence of an output schema reduces the need to describe return structure, but additional detail would improve transparency.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning: generation, single SELECT, validation, natural-language source, and non-execution.

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 2-parameter tool with an output schema, the description covers the primary purpose but lacks explicit parameter clarification and usage alternatives relative to many siblings. It is minimally complete but not richly contextual.

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?

Input schema has zero parameter descriptions, so the tool description must compensate. It implicitly maps 'question' to the natural-language question, but connection_id is not mentioned at all. The description adds only partial meaning and fails to clarify the role of connection_id in generating SQL.

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

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

The description clearly states the tool generates one validated SELECT from a natural-language question and explicitly says it does not execute it. This specific verb-resource pair ('generate ... SELECT') and the execution constraint distinguish it from siblings like generate_and_execute_query and validate_sql.

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 'without executing it' provides clear context for when this tool is appropriate versus siblings that also handle execution or validation. However, it does not explicitly name alternatives or state when-not-to-use, 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?

No annotations are provided, so the description must convey behavioral traits. It does disclose that the return value excludes secrets, which is a meaningful behavioral detail. However, it does not mention whether the operation is read-only, what happens if the connection_id is invalid, or any permission requirements. The 'without secrets' phrase adds some transparency, but other aspects are 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?

The description is a single, front-loaded sentence with no redundant words. It states the action, target, and a key differentiator (without secrets) in a minimal and efficient manner.

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 that an output schema exists (as indicated by context), the description does not need to detail return values. The tool is simple with one parameter, and the description covers its main purpose. However, it lacks usage context (when to prefer this over list_connections or test_connection) and does not explain what an 'adapter capability matrix' is, which might be ambiguous to users unfamiliar with the domain.

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

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

Schema description coverage is 0%, and the description does not explicitly explain the connection_id parameter. It implies that the tool operates on a specific connection, and the parameter name itself is suggestive, but the description adds no direct clarification about the parameter's format, uniqueness, or how to obtain a valid identifier. This falls short of compensating for the lack of schema descriptions.

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

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

The description clearly specifies the action ('Return'), the resource ('one connection'), and the specific output ('adapter capability matrix'). It also notes that secrets are excluded, which further defines the scope. This effectively distinguishes it from sibling tools like list_connections (which likely lists all connections) and test_connection (which tests connectivity).

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 explicit guidance on when to use this tool versus alternatives. It does not mention that this tool is for retrieving a single connection's capabilities, nor does it compare with list_connections or test_connection. The user must infer usage from the tool name and context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation returns data ('Return freshness...') and implies read-only behavior via 'Return' and the tool name, but it does not explicitly state that no side effects occur, whether authentication is needed, or how invalid connections are handled. This leaves some ambiguity for an agent expecting full transparency.

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

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

The description is a single, front-loaded sentence with no redundancy. It communicates the core action and scope efficiently, earning every word's 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 tool with one optional parameter and an output schema, the description is minimally adequate but lacks depth. It does not explain what 'freshness' or 'last refresh state' entails beyond literal wording, nor does it provide usage context among sibling tools. The output schema likely covers return structure, but behavioral and selection guidance are sparse.

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. The phrase 'one or all connections' directly clarifies that connection_id is optional and that null means all connections, while a value targets a specific one. This adds meaning beyond the raw schema, which only shows 'string|null' with no explanation. However, it does not define exact output formats or error behavior.

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

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

The description uses a specific verb and resource: 'Return freshness and last refresh state' for 'connections.' This clearly distinguishes it from sibling tools like refresh_schema_cache (which refreshes) and list_connections (which lists connections). It also notes the optional scope ('one or all'), adding precision.

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 is given on when to use this tool versus alternatives. While 'freshness' implies a use case for checking cache status, the description does not explicitly mention when to prefer this over refresh_schema_cache or other connection tools. There are no exclusions or contextual cues beyond the basic purpose.

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

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

With no annotations, the description must fully disclose behavior. It states the tool 'reports' liveness and versions, implying a read-only, non-destructive operation. However, it does not explicitly mention side effects, permissions, or confirm that it does not modify any state. The lack of these disclosures is a minor gap for such a simple health-check 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?

The description is a single concise sentence, front-loaded with the action and target. Every word adds value, and there is no redundant or filler text. It is exemplary in conciseness.

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

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

The tool is simple, has no parameters, and includes an output schema, which the description does not need to explain. The description fully covers the tool's purpose and expected information. A slight lack of context around what 'contract versions' entails is the only minor omission.

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 input schema has no parameters, and schema description coverage is 100% by vacuity. With zero parameters, the description does not need to explain anything further. Baseline 4 is appropriate as there is no complexity to compensate for.

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

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

The description uses the specific verb 'Report' and clearly identifies the resource: MCP process liveness and server/contract versions. It distinguishes this diagnostic tool from sibling operations like query execution or schema management by focusing on health/status information.

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

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

The description implies usage for checking MCP server health but does not explicitly state when to use it versus alternatives. There is no mention of prerequisites or situations where this tool is not appropriate. The context is clear enough that an agent would infer its purpose, but explicit guidance is missing.

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

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

With no annotations provided, the description carries the full burden. It discloses a behavioral trait ('deterministic'), implying consistent output and no side effects, but it does not explicitly state read-only behavior, error conditions, or what happens without parameters. For a trivial tool this is acceptable but minimal.

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 conveys the tool's purpose and key behavior. No wasted words; every element 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?

The tool is simple, and the output schema exists, so return values need not be described. However, the parameter 'name' is unexplained, and the description does not clarify whether the greeting changes based on it. This minor omission prevents a higher score.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'name' parameter. The description never mentions the parameter or how it affects the greeting, leaving users to guess. This is a significant 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?

The description clearly states the tool's function with a specific verb ('Return'), a resource ('a deterministic greeting'), and its purpose ('verify MCP connectivity'). This distinguishes it uniquely from all sibling tools, which are data-related.

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 explicitly states the context for use: 'used to verify MCP connectivity.' It does not mention alternatives or exclusions, but the purpose is unambiguous. Given that sibling tools like health_check and test_connection might overlap, a brief note on when to prefer this tool would have earned 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?

With no annotations, the description carries the burden of disclosing behavior. It explicitly promises 'without secrets', which is a critical safety guarantee for an agent handling sensitive data. However, it does not explicitly state that the operation is read-only or free of side effects, though 'list' implies this.

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

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

The description is a single, focused sentence that is front-loaded with the verb and resource. Every word earns its place, and there is no 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?

Given the tool's simplicity (no params, straightforward listing) and the presence of an output schema, the description provides sufficient context. It covers the key behavioral guarantee about secrets, though a brief mention of what 'adapter capabilities' entails could make it 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?

The tool has zero parameters, so the description has no need to explain parameter syntax or semantics. Per the baseline for 0 params, the score is 4.

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

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

The description uses a specific verb ('list') and resource ('configured connections and adapter capabilities'), clearly distinguishing it as a listing operation. The qualifier 'without secrets' adds specificity about security behavior, setting it apart from potential sibling tools that might fetch connection details.

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

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

The description implies usage when an agent needs to enumerate configured connections or capabilities, but it does not provide explicit guidance on when to prefer this tool over siblings like get_connection_capabilities or test_connection. No exclusions or alternative scenarios are mentioned.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It indicates a read-only operation but lacks details on pagination, result size, ordering, or permissions. The description does not even clarify whether it returns document summaries or full content.

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

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

The description is a single sentence that is front-loaded with the core action and resource. Every word is purposeful, with no redundancy or irrelevant detail.

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

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

The tool is simple (2 optional params) and has an output schema, so return values are adequately covered externally. However, the description lacks behavioral context like pagination and does not explicitly differentiate itself from search_documents. It is minimally viable but leaves room for improvement.

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 description adds meaning by mentioning 'connection and/or domain,' which maps to the connection_id and domain parameters. However, it does not specify the value format or how the filters combine (AND vs OR), leaving ambiguity.

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

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

The description clearly states the action ('List') and the resource ('indexed documents'), with explicit optional filters ('connection and/or domain'). It distinguishes itself from sibling tools like search_documents and delete_indexed_document by its specific focus on listing indexed documents.

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

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

There is no guidance on when to use this tool versus alternatives such as search_documents or refresh_document_index. The description simply states the function without contextualizing its role among the sibling tools, leaving the agent to infer usage.

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

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

With no annotations provided, the description carries the full burden. It adds useful behavioral context by specifying 'visible, non-system' collections, implying filtering of internal collections. However, it does not explicitly confirm read-only behavior, permission requirements, or potential errors, leaving gaps for an agent to infer.

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

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

The description is a single concise sentence (10 words) that is front-loaded with the action verb. Every word contributes meaning, and there is no superfluous 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?

The tool is simple with one parameter and an output schema, so return values are covered by the schema. However, the description lacks parameter semantics and usage guidance, and with no annotations, the behavioral context is thin. It is adequate but leaves notable gaps for an agent to discover.

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% for the single parameter connection_id. The description mentions 'MongoDB connection' but does not explicitly explain that connection_id identifies which connection to use. The parameter name is self-explanatory to a degree, but the description adds no direct parameter mapping or type details.

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

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

The description uses the specific verb 'List' with the resource 'visible, non-system collections for a MongoDB connection,' clearly distinguishing it from sibling tools that handle SQL tables, indexes, or connections. The scope is well-defined and matches the tool name.

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

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

The description implies usage for MongoDB connections, but it does not explicitly state when to choose this tool over alternatives like list_tables or list_schemas. There are no exclusions or alternative names mentioned, so guidance is only inferred from the MongoDB context.

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

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

With no annotations, the description carries the burden. It discloses that the list is from a cache and that schema filtering is optional, adding useful context. However, it does not mention permissions, side effects, or the nature of the returned data beyond what the output schema may show.

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

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

The description is one concise and front-loaded sentence with no filler. It communicates the core purpose efficiently.

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 list tool with an output schema, the description is minimally viable. However, it lacks parameter semantics and usage guidance, and it does not fully clarify the caching behavior's implications, leaving some gaps for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate for parameter explanation. It only hints at the 'schema' parameter through 'restricted to one schema' but does not explain the required 'connection_id' or provide format/optionality details for either 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?

The description clearly states the action (List), the resource (cached procedures and functions), and the optional restriction (one schema). It distinguishes from sibling tools like list_tables and list_schemas by specifying procedures/functions and the caching behavior.

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 is given on when to use this tool versus the many list_* siblings (e.g., list_tables, list_triggers). It does not mention any exclusions, alternatives, or scenarios where this tool is preferred.

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

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

With no annotations, the description must disclose behavior, but it only says 'List' which implies read-only. It does not explain filter semantics (e.g., exact vs partial match, AND vs OR), whether all relationships are returned when no filters are provided, or any limits or pagination.

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

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

The description is a single concise sentence, front-loaded with the main action. It avoids fluff, but is slightly too terse, omitting useful details that could be added without sacrificing conciseness.

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 tool with 3 parameters, no annotations, and only a vague description, completeness is lacking. Although an output schema exists, the description fails to explain the filtering behavior, required parameters, or how 'source or target' relates to the input fields, leaving an agent to infer too much.

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

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

Schema description coverage is 0%, so the description should compensate. It mentions 'optional filters' but does not name the table or schema parameters, nor explain how they combine or relate to source/target. The required connection_id is not mentioned at all.

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

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

The description clearly states the tool lists foreign keys filtered by source or target. This is a specific verb+resource+scope, and it distinguishes from sibling tools like list_tables or list_schemas.

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

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

No guidance is given on when to use this tool versus alternatives. The description does not mention prerequisites, such as requiring a connection_id, or contrast with similar listing tools.

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

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

With no annotations, the description carries the full disclosure burden. It discloses that the operation uses a cached snapshot (implying non-live data), but does not detail what happens if the snapshot is missing, what 'visible' means (e.g., permission filtering), or that it is a safe read-only operation. Some behavioral context is provided, but gaps remain.

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

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

The description is a single, concise sentence that front-loads the action and object. Every word earns its place, with no redundant or filler content.

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 list tool with an output schema present, the description covers the core function but lacks guidance on cache freshness, prerequisites (e.g., connection must be selected or connection_id must be valid), and the meaning of 'visible.' It is adequate but could be more complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explicitly clarify the connection_id parameter. It refers to 'selected connection' without clearly indicating that connection_id is the required identifier. The description adds little meaning beyond the schema's parameter name.

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

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

The description uses a specific verb ('List') and resource ('schemas') with a clear scope ('from the selected connection's cached snapshot'). It distinguishes itself from sibling tools like list_tables and list_procedures, as it specifically targets schemas.

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

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

The phrase 'cached snapshot' implies a read-only, non-live operation, giving some usage context. However, it provides no explicit when-to-use guidance or alternatives, such as pointing to refresh_schema_cache when the cache is stale. The usage 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?

With no annotations provided, the description carries the behavioral disclosure burden. It reveals that the tool returns cached tables (not live) and that results can be optionally filtered by schema. However, it does not disclose other behavioral aspects such as authorization requirements, side effects, or how missing schema affects the result set. The key 'cached' detail is useful, but overall transparency is moderate.

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

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

The description is a single, front-loaded sentence that states the core action and a key variation. Every word earns its place; there is no redundancy or extraneous detail. This is an excellent example of concise, effective tool documentation.

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 tool's simplicity and the presence of an output schema that covers return values, the description is largely complete. It conveys the main action, the optional filter, and the 'cached' aspect. It could be improved by stating that omitting the schema returns all tables for the connection, but the phrase 'optionally restricted' implies this. Overall, the description is sufficient for a tool of this complexity.

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 input schema has no parameter descriptions (0% coverage), so the description must compensate. It explicitly clarifies the 'schema' parameter's optionality and purpose ('optionally restricted to one schema'). However, it does not explain 'connection_id', which is required and central to the operation. Since connection_id is reasonably self-explanatory and the description adds meaning for schema, this is adequate but not thorough.

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

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

The description clearly states the tool's function: listing cached tables. The verb 'List' is specific, the resource is 'cached tables', and the optional schema restriction adds useful scope. This distinguishes it from sibling tools like list_schemas (which lists schemas) and describe_table (which describes one table).

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 implicit usage context by mentioning 'cached tables' and optional schema filtering, but it does not explicitly state when to use this tool over alternatives or any exclusions. For example, it doesn't mention that this is for cached tables only, nor does it point to a tool for live tables. The usage guidance 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 are absent, so description bears full responsibility. It discloses 'cached' nature, but does not elaborate on staleness, permissions, or side effects. It's a read-only list, but lacks depth.

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?

Single sentence, front-loaded, no filler.

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

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

Output schema exists, covering returns, but the description lacks usage context and parameter semantics; adequate for a simple list tool but leaves gaps.

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

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

Schema coverage is 0% and description only addresses table/schema as optional filters, omitting connection_id. It clarifies the filtering role but leaves relationship between filters unspecified.

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?

Description uses specific verb 'List' and resource 'cached triggers', with scope qualifiers 'schema and/or table'. It clearly differentiates from sibling tools like list_procedures/list_tables by the 'cached triggers' target.

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?

Description provides no explicit when-to-use or exclusions; use is implied when needing cached triggers. No alternative tools are mentioned.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states the basic operation and the optional single-file vs. full-directory scoping. It fails to mention potential side effects (e.g., overwriting existing indexes), performance implications of a full scan, or any required setup like a connection.

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

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

The description is a single sentence of 13 words, clearly structured with an either/or ('or') that mirrors the two execution modes. Every word contributes meaning; there is no redundancy or 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?

Despite the presence of an output schema, the description lacks critical contextual information for a potentially heavy or destructive operation. It doesn't warn that scanning the entire directory could be time-consuming or that reindexing might replace existing index entries. Given the simplicity of the tool (one optional parameter), the description is still incomplete for safe and effective 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?

The schema has no parameter descriptions (0% coverage), but the description compensates by explaining that 'source' corresponds to a single file when provided, and that omitting it triggers a complete directory scan. This adds useful semantic meaning beyond the bare schema definition, though it doesn't specify the acceptable format of the source value.

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

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

The description clearly states the action ('Reindex') and the two distinct resources it works on ('a single file' or 'the documents directory completely'). It is specific and differentiates itself from sibling tools like delete_indexed_document or search_documents by focusing on reindexing.

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 is provided on when to use this tool versus alternative tools (e.g., refresh_schema_cache, delete_indexed_document). The description implies two usage modes but doesn't state prerequisites, conditions, or exclusions, leaving the agent to infer the appropriate context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the action and scope but omits side effects (e.g., whether this is immediate, whether it interrupts queries, or what happens to the existing cache beyond being refreshed). This is similar to the update_drive example where lack of permission/reversibility context merited a low score.

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

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

The description is a single, front-loaded sentence that states the action and the conditional parameter behavior. Every word earns its place, and it is appropriately sized for a tool with one optional parameter.

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 tool's low complexity, one parameter, and presence of an output schema, the description covers the core behavior and parameter semantics. It could optionally mention the relationship to get_schema_cache_status or what 'enabled connection' means, but the description is otherwise complete for this simple operation.

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

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

Schema description coverage is 0%, so the description must compensate. The single parameter connection_id is clearly explained: providing it targets one connection, while omitting it (or using null) targets all enabled connections. This adds substantial meaning beyond the raw schema definition.

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

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

The description uses a specific verb ('Refresh') and resource ('schema cache'), and clearly scopes the action: one connection if an ID is given, or every enabled connection if omitted. This distinguishes it from sibling tools like get_schema_cache_status (status check) and refresh_document_index (different resource).

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

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

The description provides direct usage guidance by explaining that providing a connection_id refreshes a single connection, while omitting it refreshes all enabled connections. It gives clear context for when to use each mode, though it does not explicitly exclude scenarios or name 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?

Without annotations, the description carries the burden of behavioral disclosure. It informs the agent that the search operates on cached metadata, which is useful, but it does not mention whether the operation is read-only, how results are paginated, or what 'cached' means in terms of freshness.

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

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

The description is a single sentence, front-loaded, and free of filler. It is concise but slightly under-specified, as it does not touch on parameters or usage alternatives.

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?

Although an output schema exists, the description leaves several gaps: no parameter guidance, no usage alternatives, and no explanation of the cached-data behavior. For an agent trying to select among many sibling tools, this description 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?

The schema description coverage is 0%, and the description provides no explanation of the query, max_results, or connection_id parameters. For a tool with a required query and additional controls, the complete absence of parameter semantics is a significant 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?

The description uses the specific verb 'Search' and precisely scopes the resource as 'cached tables, columns, descriptions and relationships.' This distinguishes it from sibling tools like search_documents, which targets indexed documents.

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

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

The description clearly implies this tool is for searching the catalog, but it does not explicitly state when to prefer it over alternatives like search_documents or list_tables, nor does it provide any exclusions.

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

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

With no annotations, the description must disclose side effects, prerequisites, and behavior. It only states a read-like retrieval of cached chunks; it doesn't clarify what 'cached' means, whether connection_id is required, or any limitations. This is minimal behavioral disclosure.

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

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

One sentence, front-loaded verb, no redundant filler. It is extremely concise, though at the cost of completeness addressed 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?

For a tool with 4 parameters and no annotations, one sentence is insufficient context. It doesn't explain the relationship to indexed documents, domain filtering, or connection requirements, nor differentiate from sibling search tools. Output schema reduces the need to describe returns, but other context 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 0%, so the description should compensate for undefined parameters. It only alludes to 'query' and leaves domain, max_results, and connection_id unexplained. Parameter names offer some self-evidence, but the description adds little beyond the schema.

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

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

The description uses a specific verb ('Retrieve') and identifies a clear resource ('cached document chunks') with a scoping qualifier ('most relevant', 'for a query'). It broadly distinguishes from sibling tools like search_catalog and list_indexed_documents, though it doesn't explicitly name alternatives.

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

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

There is no guidance on when to use this tool versus siblings such as search_catalog or list_indexed_documents. The phrase 'for a query' implies a semantic search use case, but no exclusions or alternatives are mentioned.

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

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

The description discloses key safety traits: 'bounded read-only operation' indicates the tool is non-destructive and limited in scope. It also implies a precondition (connection must be enabled). However, with no annotations provided, the description carries a heavy burden and does not mention error behavior or whether state changes occur.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently communicates the tool's purpose and safety profile, earning 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?

Given the tool's simplicity and the existence of an output schema, the description is adequate but has gaps: it does not provide usage alternatives or parameter guidance. It barely meets the minimum viable threshold for a simple test 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?

The schema has zero description coverage, so the description must compensate. It only refers to 'an enabled connection' and does not explain the connection_id format, where to obtain it, or any constraints. The parameter name is self-explanatory but the description adds no detail, which is insufficient for a 0% coverage case.

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

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

The description specifies a clear verb ('test'), a resource ('an enabled connection'), and a method ('bounded read-only operation'), which distinguishes it from siblings like health_check that likely target system health. However, 'test' is somewhat generic and could be more explicit about verifying connectivity.

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 'enabled connection' implies a precondition, but there is no explicit when-to-use guidance or reference to alternative tools such as health_check or get_connection_capabilities. Usage context 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?

With no annotations, the description carries the full burden. It discloses the key non-execution behavior, but does not explain what validation entails (e.g., syntax checking, server-side parsing) or whether it requires an active connection. This is minimal but not misleading.

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

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

A single sentence with no filler. It front-loads the verb and resource, and every word contributes meaning. Perfectly concise.

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

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

For a 5-parameter tool with sibling execution variants, the description is too sparse. It does not clarify which parameter combinations are valid (e.g., filter for find, pipeline for aggregate), how validation differs from execution, or what the output schema represents. The output schema exists but the description still needs to guide correct invocation, especially given the many similar Mongo 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 0%, and the description offers no parameter-specific guidance. It only hints at 'filter' and 'pipeline' via the phrase 'find filter or aggregation pipeline', but does not explain the 'operation' enum, 'collection', or 'connection_id' requirements. The description fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool validates a find filter or aggregation pipeline without executing it. It uses a specific verb ('validate') and resource ('find filter or aggregation pipeline'), distinguishing it from sibling execution tools like execute_mongo_find and execute_mongo_aggregate.

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 'without executing it' implies use as a pre-flight check before running a query, providing clear context. However, it does not explicitly name alternatives or state when not to use it, such as for SQL validation (validate_sql exists as a sibling).

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the key non-execution behavior, which is important, but does not mention error handling, permissions, or the format of classification results.

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

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

The description is a single, front-loaded sentence with no superfluous words. It efficiently conveys the core action and a critical constraint.

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

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

The tool has an output schema, so return values need not be described. The core behavioral guarantee (no execution) is covered, but more detail about prerequisites (e.g., active connection) and failure modes would strengthen completeness.

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?

With 0% schema description coverage, the description should compensate by explaining parameter semantics. It only maps indirectly to 'selected connection' and 'SQL'; it does not define connection_id format, SQL dialect, or how classification is returned.

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 ('Parse and classify SQL') and resource ('for the selected connection'), and explicitly notes the tool does not execute the SQL. This clearly distinguishes it from execution-focused sibling tools like execute_read_query.

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 provides no explicit guidance on when to use this tool versus alternatives such as explain_query or validate_mongo_query. It implies validation use case but does not mention exclusions or fallback tools.

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