chat_with_workspace

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

Annotations declare the safety profile (not read-only, open-world, non-idempotent) but the description adds substantial context beyond that: up to 20 prior turns trimmed to ~12,000 chars, side effects of persisting both message and reply as knowledge-base chat entries, the assistant's limited visibility (only chat history, not reports/notes/files), the remote-or-local provider routing, and the error condition when no provider is configured.

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?

Front-loaded with the core action and return type, then progressively layers constraints, provider behavior, and sibling routing. Every sentence carries distinct information with no redundancy for a tool of this complexity.

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 non-idempotent, open-world conversational tool with no output schema, the description covers the return format (plain text), the history/context limits, the persistence side effects, the provider dependency and its failure mode, and the key gotcha that the assistant cannot see the rest of the workspace. Nothing an agent needs to call it correctly is missing.

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 100%, so both parameters (message, workspace) are already documented in the schema. The description reinforces behavior (history is sent along, entries are saved) but adds little parameter-specific syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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 a specific verb+resource+return type: 'Send a message in a workspace's ongoing chat and get the assistant's reply as plain text.' It explicitly frames the tool as multi-turn conversation, which cleanly separates it from the one-off summarize_text and the read-only list_knowledge siblings.

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 explicit routing: 'For a one-off summary of some text use summarize_text; to read stored entries use list_knowledge.' This names both alternatives and the conditions that select them, so an agent knows exactly 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.