store_search

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

Beyond the readOnlyHint and destructiveHint annotations, it explains the exact tokenization behavior, AND logic, substring matching, pagination via cursor, and the empty-query result. This provides substantial behavioral clarity an agent needs to reason about the call and interpret results.

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 compact and well-structured. It front-loads the core purpose, then explains matching semantics, pagination, edge-case behavior, and safety in four efficient sentences with no filler.

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 still specifies the return shape and pagination contract. Complex behaviors such as token matching and cursor round-tripping are fully disclosed, and required context like collection scope is explained. The agent has enough information to invoke the tool and interpret the response correctly.

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 carries the weight for parameter semantics. It thoroughly explains query semantics and cursor pagination, but it does not explain app_id, collection, or limit beyond what their names suggest. This is strong compensation but not complete.

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 names a specific verb and resource: full-text search on exactly one SOIL collection. It distinguishes itself from broad/global search tools by emphasizing 'one' collection, which differentiates it from the sibling store_search_all.

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 gives clear context: use it for full-text search within a single collection, and notes it is read-only and confined to store_scope. However, it does not explicitly mention alternative tools like store_search_all or store_get, nor state when not to use it.

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