get_dataset

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

readOnlyHint=true already tells the agent this is a safe read, so the description does not need to re-establish safety. It does add beyond the annotations by disclosing the payload's conceptual contents and a token-cost trade-off versus get_dataset_variables. It stops short of covering size/scope of the response or whether the variable list is embedded in the metadata, which matters given there is no output schema.

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?

Three short lines with clear front-loading: what it returns, then sibling routing, then scope, then a runnable example. No sentence is redundant and the alternative-tool pointers are load-bearing rather than filler.

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 no output schema, the description carries responsibility for explaining returns, and it does list the metadata facets (description, class, structure, purpose). Combined with explicit sibling routing and scope limits, an agent can select and call this correctly. Slightly incomplete in that it never says whether variables are included or how large the response is, which the token-cost remark hints at but does not resolve.

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 the baseline is 3; the description earns above that by supplying a concrete invocation example (standard='sdtmig', version='3-4', dataset='DM') that demonstrates how the three required parameters combine in practice. The scope restriction to SDTM/SEND/CDASH further constrains which standard values are meaningful, which the schema alone does not signal.

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 states a specific verb and resource ("获取指定数据集的元数据") and enumerates the payload contents (description, class, structure notes, purpose), so an agent knows exactly what comes back. It also names the sibling tools it is *not* (get_dataset_variables, get_variable, get_datastructure), making it unambiguous within a very crowded sibling set.

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?

Explicit routing is given: use get_dataset_variables when only the variable list is needed (cheaper on tokens), get_variable for a single variable, and get_datastructure for ADaM structures. This is exactly the when-to-use/when-not-to-use/alternative pattern. A minor caveat: the schema enum accepts 'adam'/'adamig' as standards while the text steers ADaM work elsewhere, but 'data structure' vs 'dataset' is a defensible distinction.

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