hint

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

Annotations already state readOnlyHint=false and destructiveHint=false, and the description does not contradict these. It adds context by explaining the meaning of set_state values (rejected/deferred/pending) and noting that compare shows the Review page. It does not explicitly disclose side effects of set_state beyond state changes, but that is implied. The description gives enough behavioral context beyond the 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 information-dense but well-organized. It front-loads the domain, then breaks down actions in a compact list, and ends with the acceptance routing. There is no fluff, though it is slightly long. It earns a high score for efficiency, though not perfect conciseness due to its length.

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 tool with 11 parameters, an action enum, and no output schema, the description covers the main actions and the acceptance alternative, but it omits which parameters are required for each action (e.g., set_state likely needs hintId and state) and what each action returns (e.g., summary returns counts, list returns a page of hints). This leaves gaps for an agent attempting to construct calls correctly.

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 only 18%, so the description must compensate. It explains the action enum and links firstName/lastName/page/pageSize to the list action, and explains the state enum for set_state. However, key parameters like hintId, collectionId, and recordId are not explained in the context of compare or set_state, leaving the agent to infer their purpose from the schema names. It partially compensates but not fully for the low coverage.

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 the tool's domain (Ancestry hints) and enumerates the four actions with concise explanations (summary counts, list pending hints, compare side-by-side, set_state for rejection/deferral). It explicitly distinguishes from sibling tools by directing acceptance to record.save_to_person and media.copy_from_tree, so an agent can tell exactly what this tool is for versus alternatives.

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?

Provides explicit guidance on when to use this tool (for hint management and comparison) and when not to (for acceptance), naming the specific sibling tools to use instead. It also instructs to compare before accepting, which is a clear usage rule. No ambiguity remains about the intended workflow.

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