ecp_mongo_browse_documents

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the authentication requirement (db_username/password must be a user this account owns), which is useful. However, it doesn't disclose pagination behavior, default page size, sort behavior, what the response looks like, or whether this is a read-only operation. For a browse tool with 9 parameters, this is a significant gap.

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

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

The description is two sentences and front-loads the core purpose ('Browse documents in a collection') before the credential note. Every sentence earns its place, and there's no fluff. It's concise, though it could add more behavioral detail without becoming bloated.

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 9 parameters, 0% schema coverage, no output schema, and no annotations, the description is incomplete. An agent needs to know how filter, sort, and pagination work, what the response format is, and whether any side effects occur. The credential requirement is a good start, but the overall context is insufficient for correct invocation, especially for the filter object.

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 undocumented parameters. The description only mentions db_username/password and collection browsing, but doesn't explain the meaning of page, page_size, filter, sort_field, sort_direction, db_name, or collection_name beyond what the schema names imply. The filter object is a nested object with no explanation of its structure (e.g., MongoDB query syntax). This is a substantial gap given 9 parameters and 0% 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?

The description states a clear verb and resource: 'Browse documents in a collection.' It distinguishes this from other Mongo tools by focusing on browsing/reading documents, and the sibling list includes insert/update/delete document tools, so the read intent is clear. However, it doesn't explicitly name a sibling alternative or contrast with other browse tools (e.g., ecp_mssql_browse_rows, ecp_postgres_browse_rows), so it's clear but not fully differentiated.

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 context: it's for browsing documents in a Mongo collection, and the credential requirement ('Connects as the given db_username/password, which must be a user this account owns') gives a prerequisite. However, it doesn't explicitly state when to use this vs. alternatives like ecp_mongo_list_collections or ecp_mongo_insert_document, nor does it mention exclusions or when not to use it. The usage context is implied but not explicit.

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