Resolve Person

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

Annotations already declare readOnlyHint=true, and the description reinforces it ('Writes nothing') while adding genuinely new behavior: the resolved details are session-only and must never be persisted into a memory file, and resolution pulls from whichever vault holds the record. It omits failure behavior (invalid or unknown identifier) and does not describe pagination or rate limits, but the added data-handling constraint is significant context beyond the annotation.

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 purpose and identifier forms are front-loaded in the first sentence, and the constraint about not persisting details follows. It is dense with subordinate clauses and the colon-list construction is slightly heavy, but every sentence carries 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?

With one parameter and no output schema, the description supplies what an agent needs: accepted identifier forms, the returned fields, the source vault, and the prohibition on writing the result into memory. The only minor gap is behavior on a non-resolving identifier, which is peripheral for a read-only lookup.

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 100% and the pattern plus example already document the single id parameter, so the schema does the heavy lifting. The description nonetheless adds real meaning by decoding the prefixes (con_ = label, ctc_, usr_) into the kinds of records they denote, which is not expressed by the regex.

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?

Specific verb ('read back') plus resource ('a person') plus the exact identifier forms accepted (con_, ctc_, usr_) and the fields returned (label, name, phone, email). No sibling tool in the list touches persons, and the description makes that scope unambiguous without opening the schema.

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?

It states the triggering context clearly: use this when a team memory references a person by identifier, and it implies the resolution step happens after reading a memory. It does not name an alternative tool or state what to do when an identifier is unknown, so it falls short of full when/when-not guidance.

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