Insert a single JSON document or an array into a MongoDB collection and return the inserted _ids; set ordered=false to continue after failed documents.
Insert one document (JSON object) or many (JSON array). Returns the inserted _ids. ordered=false keeps inserting after a failing document.
| Name | Required | Description | Default |
|---|---|---|---|
| ordered | No | ||
| database | No | ||
| documents | Yes | ||
| collection | Yes | ||
| connection | No |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a write operation, non-idempotent, and non-destructive. The description adds useful behavioral context: it returns inserted _ids and ordered=false continues inserting after a failing document. It still omits permissions, duplicate-key behavior, and the default ordered=true stopping behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both front-loaded and purposeful. The insert behavior and return value come first, followed by the important ordered=false exception.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core insert purpose, return value, and failure-handling nuance, and annotations cover the safety profile. However, with five parameters at 0% schema description coverage and no output schema, the missing collection/database/connection semantics and duplicate-error behavior leave meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all five parameters. It explains that documents may be a single object or array and what ordered=false does, but collection, database, connection, and default ordered=true behavior remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: insert documents, accepting either one JSON object or a JSON array, and returning inserted _ids. The operation is inherently distinguishable from replace_document and update_documents, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this instead of replace_document or update_documents, nor are prerequisites or exclusions given. The only conditional guidance is the ordered=false failure behavior, which is more about parameter semantics than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.