search_project_assets

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

With no annotations, the description carries the burden and does well: it discloses the unusual async behavior (first call queues the native index, re-call with the same request_id and query), and the return contents (paths, dimensions, measured geometry, declared license). Auth, rate limits, and failure modes are not covered, keeping it out of the top band.

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 first sentence ('rank names, tags, materials, notes and desired size') is dense and reads ambiguously about what is ranked versus searched. The workflow and preview guidance are front-loaded and useful, but overall the phrasing could be tightened.

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-param tool with no annotations and no output schema, the description covers the async workflow, the returned fields (including the output schema's role), and the follow-up preview step, so an agent has enough to invoke it correctly; only the limit param is left unexplained.

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. It explains request_id (re-use the same value on the poll call), query (keyword with Chinese aliases), and size (a desired-size ranking input), but says nothing about limit, leaving one of four params undocumented in both schema and prose.

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 final sentence ('This is local keyword search with Chinese aliases') states a specific verb and resource, and the opening frames it as indexing/ranking project meshes and prefabs. It is clear what the tool does, but it never explicitly differentiates itself from the sibling search_assets.

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?

It gives a real workflow cue: the two-phase queue-then-poll pattern, and it routes to reuse_project_asset(mode='preview') before placement. However, it never states when to pick this over sibling search_assets, so the when-to-use guidance is implied rather than explicit.

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