plot_probe

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

With no annotations, the description carries the full burden of behavioral disclosure. It honestly states the geometry dependency and the condition that sorted units are marked only after a sort has been run, but it does not mention response/return behaviour or confirm that the tool has no side effects.

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?

The description is compact, with the main figure content front-loaded and the prerequisite in a short second sentence. The only minor issue is the awkward 'Figure:' lead-in, but there is no filler or redundancy.

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 straightforward plotting tool, the description covers the displayed content, time window, conditional marking of sorted units, and the geometry prerequisite. It leaves out session-open requirements and explicit mapping of t0/duration_s, which is a gap but not a severe one given the tool's simplicity.

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%, so the description should compensate, but it only vaguely refers to 'a window' without naming t0 or duration_s, and it never clarifies session_id. The description adds some conceptual meaning but fails to properly explain the three parameters.

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 a specific output, the array map with contacts coloured by firing rate, and adds detail about area labels and sorted units. This makes it distinguishable from plotting siblings like plot_raster or plot_psth, though it never explicitly states the plotting action or names an alternative.

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?

The description implies when to use this tool, namely to visualise probe firing rates on an array map, and gives a clear prerequisite: geometry must exist or be set via set_probe_geometry. It does not provide explicit when-not-to-use guidance or compare against plotting alternatives.

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