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

Beyond the annotations, the description discloses that uncached resolution may invoke embeddings and the identity judge, requires editor permissions, and asserts no concept addition or usage increase. This gives a clear side-effect/cost picture without contradicting the idempotentHint/openWorldHint annotations.

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 dense but every sentence earns its place: purpose, permission/cost, return values, usage decision, parameter caveat, and inspection advice. Key purpose is front-loaded.

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 an output schema and rich parameter descriptions, this is complete for an agent to call correctly: it explains return semantics, when to use, side effects, and the one non-obvious parameter behavior. Minor omissions like judge_floor default behavior are already in the schema, so not significant.

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?

The input schema already covers 80% of parameter semantics, and the description adds meaningful guidance for embedding_model ('select the space for a new concept type, not change an existing type's space'). It also clarifies judge evidence and matched-concept behavior, going beyond the schema's basic descriptions.

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 opening sentence states a specific action ('Preview identity resolution') and explicitly constrains it ('without adding a concept or increasing its usage'), distinguishing it from mutation siblings like add_semantic_concept. The output vocabulary and use of 'probe' make the tool's role unmistakable.

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?

'Probe before adding; a matched incumbent may already represent the intended entity' is an explicit when-to-use instruction tied to the add workflow. The description also specifies the editor requirement and when embedding_model applies, so an agent can decide between this and add_semantic_concept.

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