memory.find_duplicates

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 transparently explains that the tool performs a similarity search (list), describes the threshold behavior with calibration details for different embedding models, and notes that omitting the project parameter uses the agent workspace folder. There is no contradiction with annotations (none exist).

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 concise and front-loaded. The first sentence states the core purpose and critical usage instruction ('Chame ANTES'). Every subsequent sentence adds value—threshold calibration, parameter guidance, and sibling references. There is no redundant or extraneous text.

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 (6 parameters, many sibling tools, and an output schema), the description provides sufficient context for an agent to select and invoke this tool correctly. It explains the primary use case (duplicate detection), how to set the threshold, and how to use the result with other tools. The output schema exists, so detailing return values is not required. The missing parameter descriptions are a minor gap but do not undermine overall contextual 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?

Schema description coverage is 0%, so the description must compensate. It adds meaning for three of six parameters: 'text' as title+summary of intended memory, 'threshold' with calibration values, and 'project' as optional with agent workspace default. However, it provides no explanation for 'type', 'memory_scope', and 'memory_branch', leaving a gap for those 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 that the tool lists similar memories with a minimum similarity threshold, and ties it to the purpose of avoiding duplicates. It distinguishes from siblings by explicitly mentioning that it should be called before creating a memory and referencing sibling tools like memory.upsert and memory.manual.create for further action.

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 explicit when-to-use guidance: 'Chame ANTES de criar p/ evitar duplicatas'. It also gives clear alternatives based on the result: create new via memory.upsert or memory.manual.create, or refine existing via search-before-write. This directly informs the agent's decision-making.

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