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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's main added context is that existing sources are inspected before adding. It never explains what "resync" actually does — whether it overwrites, duplicates, or silently no-ops on an already-present study, which matters given idempotentHint=false.

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?

Two short sentences with the action front-loaded and no filler. The second sentence is slightly vague in phrasing but still earns its place as a scoping constraint.

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?

An output schema exists, so return values need not be explained. However, for a non-read-only mutation with a non-idempotent hint, the definition leaves unclear what a sync does to an already-synced study and what "sources" refers to in the Hub session model.

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 only 33%: study_id and session_id carry no description beyond UUID format, and only organization_id is documented (in the schema itself). The description names no parameters, provides no format/syntax detail, and does not clarify the session_id vs study_id relationship, so it fails to compensate for the coverage gap.

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 ("Add or resync one study in a Hub session"), and the word "one" implicitly contrasts with add_all_research_studies. It does not name any sibling explicitly, so the differentiation is left to inference rather than stated.

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?

"Add only the study the user requested" hints at the single-study use case and implies add_all_research_studies is the bulk alternative, but no alternative is ever named and no when-not condition is given. The instruction to "inspect existing sources" reads more like an internal workflow hint than selection guidance.

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