search_contents

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

The read-only and non-destructive behavior is already declared in annotations, and the description adds useful behavioral details like empty-search rejection, default types, and the absence of a list-all mode. It does not describe result ordering, pagination, or whether archived items are included, but these are less critical given the annotation coverage.

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, with each parameter explained on its own line. The warning about empty strings and the browse alternative are included without unnecessary verbosity.

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?

While the available output schema may cover return values, the description does not address several important filtering parameters, especially hub_profile_id and only_archived, which are directly relevant to the search scope. This leaves the tool incomplete for an agent trying to use it effectively with all its capabilities.

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?

Only three of eight parameters are described: workspace_id, search, and types. The required hub_profile_id is not explained at all, and only_archived and all exclude_* parameters are omitted, leaving a substantial portion of the input schema undocumented.

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 searches content items within a hub profile by keyword, making the operation and resource explicit. It also distinguishes itself from a pure browse action by noting that search cannot list all items, which helps set it apart from sibling tools like list_contents.

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 gives concrete usage direction: workspace_id should come from list_workspaces(), search must be non-empty or the request is rejected with 400, and types can be restricted to Content, Collection, or both. The note that browsing should be done via channels/categories is actionable guidance for when not to use this tool.

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