Navigator item details

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower, and the description still adds real context: per-item partial failure results ('{id, error}'), the batch ceiling implied by maxItems, and the important caveat that viewpoint data is only present for Project Map items (a View Map item carries the viewpoint as its sourceId). It stops short of describing pagination or how many items the locate traversal costs.

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?

Front-loaded with the core purpose and then packed with type-specific specifics; the em-dash clauses are dense but each earns its place by pre-empting a follow-up question. The single long sentence/semi-colon run-on is harder to scan than a short bulleted structure would be, but nothing is wasted.

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?

No output schema exists, so the description carries the full burden of describing returns — and it does, specifying the exact response envelope, the per-item error alternative, and the type-specific payloads for stories, folders, layouts, and viewpoints. Combined with 100% schema coverage, an agent has everything needed to invoke and interpret the call.

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 is 3: both 'ids' and 'locate' are already documented, and locate's default and effect are spelled out in the schema itself. The description reinforces what the located fields are (tree, path, parentId, sourceId), but adds no parameter behavior beyond what the schema already states.

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 gives a specific verb and resource ('Returns details of navigator items by id') and then enumerates exactly what 'details' means — type, name, prefix/id, location fields, and per-type payloads. It never explicitly routes the agent away from the sibling get_navigator_tree (the id source is only mentioned in the schema), so it is clear but not sibling-aware within the description body.

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 implied rather than stated: an agent infers that this is the follow-up to get_navigator_tree for fetching per-item data, but the description never says when to prefer it over list_views, get_view_settings, or get_navigator_tree, nor when to set locate=false. No explicit alternatives or exclusions are offered.

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