oss_unit_context

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

With no annotations, the description still discloses real behavior: pagination continuation, the fact that symbols and edges are truncated to the first page, and the confidence-0.5 filter gated on all_calls. It omits read-only-ness, error behavior for an unknown unit_id, and the effect of include_calls=false, so the burden is not fully carried.

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 compact sentences with the main content statement front-loaded and pagination rules following. No wasted prose, though the reference to names not present in the schema (next_offset, next_line) adds mild confusion rather than clarity.

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 six-parameter, no-annotation, no-output-schema retrieval tool, the essentials of pagination and content gating are covered. However, the meaning of include_calls and agent, and the shape of the returned record beyond next_line, are left for the caller to guess.

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 0% across six parameters, so the description must compensate. It usefully disambiguates offset as a line ordinal within the unit (versus the returned file:line next_line) and explains all_calls, but leaves agent, project_id, unit_id, and include_calls entirely undefined.

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 names the resource precisely: unit code with line numbers, symbol list, and call edges with L0 evidence ids. That distinguishes it from list/graph siblings such as oss_units_list or oss_graph_query. It stops short of explicitly naming which sibling to use instead for a different view.

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?

It gives operational guidance (continue with next_offset when the code is large; symbols and edges appear only on the first page; low-confidence edges require all_calls=true), which implies when and how to call it repeatedly. But nothing states when to choose this over oss_unit_next or oss_lsp_call_hierarchy, and no exclusions are given.

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