analyze_trajectory_data

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

Annotations already communicate readOnlyHint=false and destructiveHint=true, so the risk profile is known. The description adds no side-effect context, such as whether trajectory results overwrite existing data or require prior preprocessing, but it does not contradict the annotations.

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 short, front-loaded, and free of fluff. The args lines add minimal value because the schema already defines the parameters, but overall this is a compact, readable description.

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?

This is a complex trajectory-analysis tool with multiple methods, method-specific parameters, and a destructive hint, but the description only provides a one-line purpose. Important selection context—such as method-specific data requirements and expected inputs—is buried in the nested schema rather than presented in the description.

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?

The description only lists 'method, root_cell, spatial_weight, etc.' in passing and does not provide meaningful parameter semantics. It also uses 'root_cell' while the schema defines the field as 'root_cells'. The actual parameter understanding relies on the rich nested schema descriptions, not the tool description.

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 sentence 'Infer cellular trajectories and pseudotime ordering' names a specific analysis task with a clear action and object. It is distinct from most sibling tools, though it does not explicitly contrast with related tools like analyze_velocity_data.

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?

No when-to-use guidance is provided: there are no hints about velocity prerequisites, when to choose palantir/dpt over cellrank, or when another analysis tool would be more appropriate. Some guidance exists only in the nested schema description, not in the tool description.

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