Team Import from External Tools

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, but the description adds nothing on top: it doesn't say that entries are written to the database, that re-running a non-idempotent import can duplicate content, or that dry_run avoids writes. For a write/import tool, that is a meaningful 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?

A single ten-word sentence with no filler and the key scope ('team journal') front-loaded. It is efficiently written, though the brevity reflects under-specification rather than disciplined selection.

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

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

An output schema exists so return values needn't be explained, but an 8-parameter, open-world, non-idempotent import tool with a dry_run mode and workspace isolation needs more than one sentence. Nothing explains the import lifecycle, file discovery from source_dir, or the effect of limit.

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 75%, just under the high-coverage baseline, and two parameters (use_test_db, project_number) have no description anywhere. The description contributes zero parameter meaning, so it fails to compensate for the undocumented parameters on a tool where use_test_db in particular could cause data to land in the wrong database.

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: import external knowledge-management exports into the team journal. The word 'team' implicitly separates it from the personal import_external / import_markdown siblings, but the description never names those alternatives or the supported formats (notion, obsidian, logseq) that would fully disambiguate.

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

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

There is no when-to-use guidance, no mention of the dry_run validation workflow, no prerequisites (source_dir must exist, source_format must be one of three values), and no routing to import_markdown or import_external. The agent must infer all of this from the schema.

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