fit_latent_factors

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

With no annotations provided, the description carries the full behavioral burden. It discloses key behaviors: GPFA returns denoised single-trial trajectories and a timescale per factor, PCA is fast but noisier, the fit produces variance_explained_per_factor, and velocity-like signal explanation is reported when present. This is strong behavioral context, though exact output structure and side effects are not spelled out.

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 and well-structured: it states the purpose, contrasts the two methods, gives dimensionality-selection guidance, and names the follow-up plotting tool. Each sentence earns its place, and the core operation is front-loaded.

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?

The description provides a solid high-level workflow and names a key output field, but for a 9-parameter tool with no annotations and no output schema, it omits important operational details such as how parameters like event, group_by, bin_s, and t_before/t_after affect the fit. It is minimally viable but not complete.

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 must compensate for undocumented parameters. It adds meaning for 'method' by comparing gpfa vs pca, but leaves bin_s, event, units, t_after, group_by, t_before, n_factors, and session_id effectively unexplained. 'Trial-aligned' hints at event timing but does not clarify t_before/t_after or bin_s.

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 opens with a specific verb and resource: 'Fit low-dimensional latent factors to trial-aligned population activity.' It also names the two methods (GPFA and PCA) and explicitly differentiates this fitting tool from the sibling plotting tool plot_latent_factors by saying that tool 'draws the trajectories.'

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 gives practical usage guidance: choose GPFA for denoised trajectories or PCA for a fast baseline, use the elbow in variance_explained_per_factor to judge dimensionality, and then call plot_latent_factors to visualize. It does not explicitly state when not to use this tool versus other analysis siblings like fit_decoder, so it stops just short of full exclusion guidance.

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