ms_list_analysis_targets

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

With no annotations provided, the description carries the full burden. 'Hash-bound, confirmed MaterialsScript run' hints at a security/confirmation workflow but doesn't specify what side effects or guarantees exist, what 'confirmed' entails, or what the output represents. Lacks transparency about behavior.

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?

One sentence is concise, but it packs in vague jargon ('hash-bound, confirmed MaterialsScript run') that obscures rather than informs. While there's no wasted words, the lack of elaboration makes it under-specified rather than cleanly written.

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 tool with 7 parameters and an output schema, this description is incomplete. It doesn't define 'analysis targets', the meaning of the confirmation hash, or the conditions under which the tool is used. The output schema exists, so return format is covered, but the operational context is missing.

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 has 7 parameters with zero descriptions, and the description doesn't mention them explicitly. The phrase 'hash-bound' suggests input_sha256 is a hash of input_document, and 'confirmed' implies confirmation_token, but this is only a hint and leaves dry_run, job_name, keep_job_dir, timeout_seconds entirely unexplained. Does not compensate for the 0% schema coverage.

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 'List analysis targets' clearly as a list operation on a specific resource, distinguishing it from sibling tools like ms_list_example_documents. However, the phrase 'hash-bound, confirmed MaterialsScript run' adds jargon without explaining what analysis targets are or the nature of the run, slightly obscuring clarity.

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?

Provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about the verification or hash requirement. Only states what it does, not when it's appropriate.

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