search_motion

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, covering the safety profile. The description's 'Corpus only' line reinforces the closed-corpus behavior and adds the live-capture contrast, which is useful but largely consistent with openWorldHint=false. Nothing is said about result shape, ranking, or how limit interacts with the corpus.

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 sentences, front-loaded with the verb and resource, then a single routing clause. No filler and nothing repeated.

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?

With no output schema, the description should convey what comes back; 'find sites that...' implies site-level results, which is adequate for a four-param, all-optional search tool. Missing details are minor — result ordering and pagination behavior relative to limit.

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 coverage is 75% (lib, hasPins, scrubOnly documented), and the description largely restates those same semantics rather than adding format, token, or matching detail. The undocumented 'limit' is self-explanatory via min/max. Baseline 3 fits when the schema already carries the parameter meaning.

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?

States a specific verb (Search) and resource (captured Motion DNA records) and then concretizes the searchable properties: pinned sections, scroll-scrubbed animation, animation libraries. It also contrasts itself with the sibling get_motion_dna, so an agent can route without opening either schema.

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?

Explicitly scopes usage to the existing corpus and names the alternative for the live path ('live-capture happens via get_motion_dna'), which is a real when-to-use/when-not split. It does not, however, distinguish itself from search_sites or search_elements, so the routing guidance is clear but incomplete.

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