ls-search

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

With no annotations, the description must disclose behavioral traits. It states the tool is destructive and returns a receipt, but does not mention irreversibility, side effects on other data, or prerequisites beyond params. Adequate but not thorough.

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 a single sentence of 12 words, concise and front-loaded. No superfluous text, but it could include more context without losing brevity.

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?

Given the simplicity of the tool (2 params, no output schema), the description provides the core action and a hint about the return value ('signed disposal receipt'). However, it lacks details like when to call it or what happens if called multiple times.

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 100%, so the input schema already explains both parameters. The description does not add any additional semantic information about the parameters beyond what is in the schema.

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 uses a specific verb ('Destroy') and resource ('workspace') and clearly states the outcome ('returns a signed disposal receipt'). It distinguishes this tool from siblings, as no other tool destroys a workspace.

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 does not provide any guidance on when to use this tool versus alternatives (e.g., after finishing work, when to avoid). No explicit context like 'use this to clean up' is given.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It states the basic action but fails to describe what happens if the item is not found, whether the operation is read-only, any required permissions beyond the token, or the exact nature of the returned data (metadata vs content). These gaps hinder an agent's ability to reason about side effects.

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?

A single sentence of 9 words, front-loaded with the core action. Every word is meaningful and there is no extraneous information. It is efficiently structured for quick comprehension.

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?

Given the absence of an output schema, the description should specify what the tool returns (e.g., full content, metadata only, or both). The ambiguous phrase 'metadata/content' and lack of any structure description leaves the agent uncertain about the response format. For a simple fetch tool, this is a notable omission.

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 67% (2 of 3 parameters have descriptions). The description adds minimal value beyond the schema: it mentions 'by item id' which mirrors the parameter name, and references workspace parameters from trace_create_workspace (already in schema). Item_id lacks description both in schema and description, so the agent gets no added semantics for the key parameter.

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 clearly states the tool fetches one item's metadata/content from a workspace by item id. The verb 'Fetch' and resource 'one item's metadata/content' are specific, and the tool is easily distinguished from siblings like trace_search (returns multiple items) or trace_get_usage (returns overall usage).

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 guidance is provided on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or exclusion criteria. An agent would not know from this description that it should be used only when a specific item id is available, or not to use it for batch operations.

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