Case- and accent-insensitive search over titles and bodies of pages, databases and rows, best matches first. Use it to locate an item by text when the workspace map does not already give you its id.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| results | Yes | Matching items |
Changes observed during successful MCP inspections.
Input schema / properties / limit / descriptionRemoved value: -"Maximum results (default 10)"Input schema / properties / query / descriptionRemoved value: -"Text to match against item titles and content (case-insensitive substring)"Output schema / properties / results / items / properties / breadcrumb / descriptionPrevious value: -"Location path from the workspace root to the item (for a database_row, ends with its parent database name)"New value: +"Path from workspace root"Output schema / properties / results / items / properties / databaseId / descriptionPrevious value: -"Parent database ID, present for database_row results (pass to query_database)"New value: +"Present for database_row results"Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Item ID (pass to get_page)"New value: +"Pass to get_page"Output schema / properties / results / items / properties / matchedOn / descriptionPrevious value: -"Where the query matched: title | content"New value: +"title | content"Output schema / properties / results / items / properties / parentId / descriptionRemoved value: -"Parent item ID for nested sidebar items"Output schema / properties / results / items / properties / snippet / descriptionRemoved value: -"Matching content snippet (empty when the match was on the title)"Output schema / properties / results / items / properties / title / descriptionRemoved value: -"Item title"Output schema / properties / results / items / properties / type / descriptionPrevious value: -"Item type: page | database | database_row"New value: +"page | database | database_row"Input schema / properties / query / descriptionPrevious value: -"Search query"New value: +"Text to match against item titles and content (case-insensitive substring)"Output schema / properties / results / items / properties / breadcrumbAdded value: +{
+ "description": "Location path from the workspace root to the item (for a database_row, ends with its parent database name)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / results / items / properties / databaseIdAdded value: +{
+ "description": "Parent database ID, present for database_row results (pass to query_database)",
+ "type": "string"
+}Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Item ID"New value: +"Item ID (pass to get_page)"Output schema / properties / results / items / properties / matchedOnAdded value: +{
+ "description": "Where the query matched: title | content",
+ "type": "string"
+}Output schema / properties / results / items / properties / parentIdAdded value: +{
+ "description": "Parent item ID for nested sidebar items",
+ "type": "string"
+}Output schema / properties / results / items / properties / snippet / descriptionPrevious value: -"Matching content snippet (pages only)"New value: +"Matching content snippet (empty when the match was on the title)"Output schema / properties / results / items / properties / type / descriptionPrevious value: -"Item type (page | database)"New value: +"Item type: page | database | database_row"Output schema / properties / results / items / requiredPrevious value: -[
- "id",
- "type",
- "title",
- "snippet"
-]New value: +[
+ "id",
+ "type",
+ "title",
+ "breadcrumb",
+ "matchedOn",
+ "snippet"
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to state read-only nature. It adds valuable behavioral details: case- and accent-insensitivity and ordering by best matches. These go beyond the schema and annotations, though it does not mention pagination or output structure (covered by output 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?
Two sentences, front-loaded with the main purpose and usage condition, no fluff or redundancy. Every word contributes to understanding the tool.
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 tool is simple with only 2 parameters and an output schema, so the description covers the core purpose and usage well. However, the missing explanation of 'limit' is a notable gap, though minor given the schema provides a default and the output schema handles return details.
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 implicitly covers 'query' by describing text search, but the 'limit' parameter is entirely absent. The description does not explain what limit controls or its default behavior, leaving the agent to infer from the schema alone, which is inadequate.
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 function: case- and accent-insensitive search over titles and bodies of pages, databases, and rows, with best matches first. It names specific resources and a specific verb, distinguishing it from siblings like get_page or list_workspace by its search semantics.
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 a clear usage condition: 'Use it to locate an item by text when the workspace map does not already give you its id.' This implies when not to use it (when you have the id) and provides context for when search is appropriate, though it does not explicitly name an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.