ls-search

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

With no annotations, the description carries full weight. It discloses ephemerality, prepaid micropayment via x402, no account/signup, and the return of a one-time capability_token. This provides robust behavioral transparency.

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 concise sentences, front-loaded with purpose and enriched with necessary operational details. No fluff or redundancy.

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?

The description covers purpose, payment flow, and output, which is sufficient given the simple 3-parameter schema and no output schema. It could mention error handling or cleanup but is otherwise complete.

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 100%, so baseline is 3. The description adds meaningful context for x_payment by explaining the two call modes and the token outcome, going beyond the schema's simple parameter 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 description opens with 'Create an isolated, disposable (ephemeral) vector-search workspace' - a specific verb with a clear resource and scope. It clearly distinguishes from sibling tools like trace_dispose_workspace, trace_ingest_batch, and trace_search.

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 provides explicit usage modes: call without x_payment to get pricing, with a signed x_payment to get a capability_token. This is clear context, though it doesn't explicitly mention alternatives or when not to use the tool.

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 provided, the description carries the full burden of behavioral disclosure. It clearly states the irreversible destructive nature ('permanently delete', 'zero data retention') and mentions the signed receipt as a consequence, which is valuable context not available in structured fields. However, it doesn't discuss authorization or rate limits, though the workspace_token parameter is present in the schema.

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, front-loaded sentence that efficiently communicates the action and the return value without unnecessary words.

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 destructive nature and lack of output schema, the description sufficiently covers the outcome (permanent deletion, zero retention) and the return value (disposal receipt). It could be more explicit about the receipt format or error handling, but it remains complete for the tool's complexity.

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 input schema already provides 100% coverage with descriptions for both parameters, so the description doesn't add additional parameter-level meaning. Baseline of 3 is appropriate as the schema handles the semantic burden.

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 the specific verb 'Dispose and permanently delete' and clearly identifies the resource (workspace and its in-memory vector index/data). It also distinguishes this from sibling tools by focusing on deletion rather than creation, retrieval, or search.

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 implies usage for permanent workspace deletion but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions like the requirement for a valid workspace token.

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 provided, the description carries the transparency burden. It accurately conveys this is a read operation returning content and metadata, but it does not disclose error behavior (e.g., missing item_id), auth requirements beyond the token parameters, or any rate limits. The description is not misleading but lacks depth.

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, focused sentence that states the action, the resource, the result, and the lookup key. No filler or redundant information; it earns its place.

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 there is no output schema, the description appropriately mentions that the return includes 'content and metadata'. For a simple get-by-id tool, this is sufficient contextual coverage. It could add error-handling details, but the simplicity and clear parameter list keep it complete enough.

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 67%: workspace_id and workspace_token have descriptions, while item_id has none. The description adds meaning by identifying item_id as the retrieval key, which is useful. However, it does not clarify the format or any special constraints on item_id, leaving room for the schema to carry the remainder.

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's action ('Retrieve a single stored passage/document/item') and the lookup mechanism ('by item id'). This distinguishes it from sibling tools like trace_search and trace_ingest_batch, which serve different retrieval and write operations.

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 usage context is implied: use this tool when you have an item id and need the content and metadata of a specific passage. However, the description does not explicitly state when NOT to use it, nor does it name alternatives like trace_search for query-based retrieval.

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?

Annotations are absent, so the description must carry the behavioral transparency burden. The description indicates a read operation ('Get') and lists the returned fields, but it does not explicitly state that the operation is non-destructive, does not incur side effects, or how auth is handled (beyond schema token parameters). It adds some context but lacks explicit behavioral disclosures.

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, focused sentence that front-loads the action and resource. It avoids redundancy and is appropriately sized for the tool's simplicity.

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 simple read-only tool with no output schema, the description lists the main return content (prepaid time, spend, counts, state), giving the agent a good sense of what to expect. It does not cover error cases or usage timing, but it is adequate for basic invocation. Could be improved by noting read-only status.

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 100% with both workspace_id and workspace_token having descriptions referencing trace_create_workspace. The description does not mention parameters or provide additional semantic meaning; per rubric, baseline is 3 for high 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?

The description begins with 'Get workspace usage and billing status', clearly identifying the verb (Get) and resource (workspace usage/billing). It distinguishes from siblings like trace_create_workspace and trace_dispose_workspace by focusing on read-only status, and enumerates specific data returned (prepaid time/TTL, spend, counts, state), making it unambiguous.

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 explicitly state when to use this tool or provide alternatives. However, from the sibling list, it is the only tool related to usage/billing, so the usage context is implied. No exclusions or when-not-to-use scenarios are mentioned, so it's not fully guided.

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?

There are no annotations, so the description must carry the full behavioral disclosure burden. The description covers the document format and binary support, but does not disclose whether the operation is asynchronous, idempotent, reversible, or what the side effects on the existing index are. For a mutation tool, this is a significant gap.

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 concise, front-loaded sentences: the first states the core purpose and destination, the second gives the essential parameter format. No wasted words or repetition of schema details.

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?

The description is adequate for a 3-parameter tool with no output schema, but it omits expected behavior after ingestion (e.g., whether it returns success/failure, how to verify indexing, or any timing constraints). Given there is no output schema, the description should hint at the result or next steps, but it does not.

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 schema has only 67% coverage (workspace_id and workspace_token have descriptions from sibling tools, but the document fields are unannotated). The description fills that gap by clearly explaining the document structure: 'name, text OR content_b64, mime?' and clarifying that text and binary (base64) are both supported, which adds meaning not present 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 clearly states a specific action ('Ingest and index') and the resource ('documents, passages or text chunks into your workspace') with an explicit purpose ('to build the searchable vector/embedding index'). This strongly distinguishes it from sibling tools like trace_search (which queries) and trace_create_workspace (which creates 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 provides clear context: this is the tool to populate the searchable index for semantic search and RAG retrieval, implying its role in the pipeline. However, it does not explicitly mention alternatives or exclusions (e.g., 'use trace_search for querying'), so it stops short of a full 'when to use vs. alternatives' statement.

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 the full burden. It discloses the output behavior ('Returns ranked passages/hits with locators') and the input constraint ('Provide query OR image_b64'). It also hints at the ephemeral nature of the index ('disposable index'). However, it does not explicitly state that the operation is read-only or describe behavior in edge cases (e.g., both query and image_b64 provided, empty index).

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 efficiently structured: it opens with a clear purpose, then adds supporting details in three sentences. Every sentence provides useful context (algorithm type, supported query modes, output, input constraint) with no redundancy or wasted words.

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 search tool with no output schema, the description covers the essential return type ('ranked passages/hits with locators') and query modes. It does not detail the exact response structure or handle the workspace lifecycle, but given the sibling tools and schema, this is adequate.

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 100%, so parameters are already documented. The description adds valuable semantics beyond the schema by introducing the 'query OR image_b64' constraint and explaining the cross-modal capabilities, which clarifies how the parameters relate to each other.

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's purpose with a specific verb and resource: 'Semantic vector search / similarity retrieval... over your private disposable index.' It explicitly identifies itself as 'the core RAG retrieval call,' which distinguishes it from sibling tools like trace_ingest_batch and trace_get_passage.

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 provides clear context for when to use the tool ('the core RAG retrieval call') and specifies input modes (natural-language, cross-modal, reverse-image). However, it does not explicitly name alternative tools or provide when-not guidance, so it stops short of a 5.

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