slice_contents

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

With no annotations, the description carries the full behavioral burden. It does disclose ordering ("largest first") and the returned attributes (area, visibility), which is useful, but it never says the tool is read-only, does not mention the area filtering behavior implied by min_area_mm2, and does not address empty results or what happens when a slice has no structures.

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 resource description and the ordering fact front-loaded, and no filler. The only inefficiency is the jargon-laden second sentence, which spends words on an unexplained term rather than on information the agent needs.

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 4-parameter tool with no annotations and no output schema, the description is thin: it omits the default filter behavior, index conventions, and the form of the returned structure entries beyond naming two fields. An agent could call it, but not predict what it receives or how the threshold affects the result.

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 4 parameters, so the description must supply meaning. It only gestures at "slice" and "area"; it never explains what slice_index indexes (base, range), what view values are valid (only in the enum), or that min_area_mm2 is a threshold defaulting to 50 mm² that suppresses small structures.

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?

"Structures visible on a slice (area, visibility), largest first" states a specific verb-and-resource plus the returned fields and ordering, so an agent knows it retrieves per-slice structure listings. It does not distinguish itself from the sibling list_structures, which plausibly returns structures at the dataset level, leaving some ambiguity about scope.

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?

"Use to choose distractors" gives one concrete use case, which is more than a bare purpose statement. However, no alternative is named (list_structures, find_slices), no when-not-to-use is stated, and the domain term "distractors" is undefined, so the agent must infer the selection conditions.

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