search

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description need not restate safety. It adds genuine behavioral value with the critical warning that extensions results carry SOURCE models and 'never use them as create/modify targets' — a non-obvious trap an agent must know. It also discloses batch dedup and cross-reference behavior, though it stops short of describing pagination or empty-result handling.

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?

Purpose is front-loaded in the opening sentence, followed by scannable bullet points per mode and one routing sentence. It is longer than the average description, but every sentence earns its place — the SOURCE-model warning and sibling routing are load-bearing. No filler or repetition of the title.

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?

For a complex 7-parameter, 3-mode tool with no output schema, the description covers purpose, mode selection, the key behavioral caveat, and sibling routing. It states single-mode returns (name, type, model) but leaves batch/extensions return structure unspecified — a minor gap acceptable given no output schema and the annotation-provided safety profile.

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%, so each of the 7 parameters is already documented (with mode-tag [single]/[batch]/[extensions] and mode-routing notes like 'Ignored when queries[] is provided'). The description reinforces the mode structure and adds the useful 'max 10' batch cap, but largely restates what the schema already communicates — appropriate for the 100%-coverage baseline.

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 ('Search pre-indexed D365FO objects by name or keyword') and enumerates three concrete modes with distinct inputs. It explicitly differentiates from the closest sibling, get_object_info, naming the exact condition ('when you already know the exact name and need full details') that selects the alternative.

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?

Gives explicit routing: 'Use get_object_info(objectType, name) when you already know the exact name' is a crisp this-vs-that exclusion. The three modes each carry trigger conditions (default single, batch for parallel with max 10, scope:'extensions' to restrict to custom/ISV models), so an agent knows exactly when and how to invoke each path.

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