datalens_workbooks_getRetrieve one DataLens workbook by ID to view its title, description, and collection. Include permission info to see what the caller may do with it.
One workbook by id: its title, description and collection.
| Name | Required | Description | Default |
|---|---|---|---|
| workbook_id | Yes | Workbook id. | |
| include_permissions_info | No | Also say what the caller may do with it. |
Changes observed during successful MCP inspections.
v0.122.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that the result is scoped to three fields, but says nothing about auth requirements, error behavior on a missing id, or how include_permissions_info alters the response.
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?
A single compact sentence with the key constraint ('by id') front-loaded and the result shape appended. No waste, though it is terse enough that it omits useful detail rather than trimming fat.
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 the burden of describing the return value, and it names only three fields while ignoring the permissions dimension of include_permissions_info. Adequate for a simple getter but leaves the response contract partially unspecified.
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 100%, so the baseline of 3 applies. The description clarifies that workbook_id selects a single workbook, but it never mentions the optional include_permissions_info parameter, leaving the schema to do all the work for the second parameter.
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?
Clear verb+resource ('Get... one workbook by id') and enumerates the returned fields (title, description, collection), so an agent knows exactly what it retrieves. It does not name the sibling it is distinct from (e.g. datalens_workbooks_list or datalens_workbooks_list_by_ids), so differentiation is left to the agent.
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?
Usage is only implied by the name and the 'by id' phrasing — fetch a single knowable workbook. There is no explicit when-to-use, no mention of when to prefer datalens_workbooks_list_by_ids for multiple ids, and no prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.