Atwork

Search Workspace

workspace.search

Read-onlyIdempotent

Search the workspace by content across sheets, pages, dashboards, items, tasks, employees, teams, and jobs. Returns up to limit ranked hits with kind/id/name/snippet. Use when the user references something by name ("the Pipeline sheet", "Sara's onboarding", "the launch blog") and you need its id to pass to other tools. Item-level search (rows inside sheets) covers all column content. Use parentSheetId to restrict to a specific sheet. Archived items are never returned; read them with sheet.read and archived: "only". Email addresses and phone numbers in names and snippets come back as [redacted].

Input Schema

Name	Required	Description
`limit`	No
`query`	Yes
`types`	No	Restrict to a subset of kinds. Omit to search all.
`parentSheetId`	No	Restrict to items inside a specific sheet (e.g. 'find rows in the Pipeline sheet matching X').

Output Schema

Name	Required	Description	Default
`results`	Yes	Ranked hits; `id` is what other tools take (items are UUIDs, top-level entities numeric ids as strings)
`truncated`	Yes	True when more hits matched than `limit` allowed

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 4, 2026
- removedOutput schema / properties / results / items / properties / name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / results / items / properties / parentSheetId / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / parentSheetId / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / results / items / properties / snippet / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / results / items / properties / snippet / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedOct 20, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds real behavior: results are ranked, capped by `limit`, and include kind/id/name/snippet. It also discloses two non-obvious traits the annotations cannot express — archived items are silently excluded, and emails/phones are returned as '[redacted]'. Only ranking criteria and pagination beyond `limit` are left unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb/resource and the when-to-use trigger, then exclusions. Dense but nearly every sentence carries information. The 'Use `parentSheetId` to restrict to a specific sheet' sentence largely restates the schema's own parameter description, which is the one mildly redundant line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter search tool with an output schema already defining the hit shape, the description covers the remaining decision-relevant gaps: when to reach for it, how to narrow scope, what is excluded, and how PII is masked. An agent can call it correctly without further context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50% (types and parentSheetId documented; query and limit bare), so the description compensates by explaining that `limit` caps ranked hits and that `parentSheetId` restricts to items inside one sheet. It also clarifies that item-level search spans all column content, which is meaning the schema does not convey. The `types` filter is left entirely to the schema and query syntax (matching behavior, operators) is not described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the workspace by content') and enumerates the searchable kinds: sheets, pages, dashboards, items, tasks, employees, teams, jobs. This clearly separates it from siblings like sheet.read (single sheet), workspace.structure (shape of the workspace), and recipe.search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete trigger ('when the user references something by name ... and you need its id to pass to other tools') with real examples such as 'the Pipeline sheet' and 'Sara's onboarding'. It also names the alternative path for the excluded case: archived items are never returned, so read them with sheet.read and archived: "only".

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

All Atwork tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?