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

Beyond the annotations, the description discloses the asynchronous internal-agent workflow, the validation step, the polling behavior via get_agent_session, the final message contents, private-by-default creation, in-place revision preserving identity and sharing, and session continuation semantics. These are meaningful behavioral details not already captured by the annotations.

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 longer but front-loaded and tightly structured; each sentence carries operational instructions for revision, asynchronous polling, session continuation, idempotency, sharing, and alternative tools. The length is justified by the multi-step asynchronous workflow being described.

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 complex asynchronous tool with no output schema, the description explains the full lifecycle: start the operation, poll get_agent_session, obtain the saved artifact folder ID and viewer link, call show_artifact, continue with sessionId, and handle sharing. No critical invocation or follow-up context 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 high at 83%, so the baseline is 3, but the description adds practical meaning for fileId (artifact folder ID, identity and sharing preservation), sessionId (follow-up only, mismatch rejection), operationId (fresh per new instruction, identical retry only), and sources (existing reports, analytics, or files). It does not fully describe the source filter/query schema, but that is appropriately left to the detailed schema.

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 uses specific verbs (research, write, save) and identifies the resource (artifact), including Insights reports. It explicitly names create_artifact and update_artifact as alternatives when the files already exist, so an agent can distinguish this tool from sibling artifact tools.

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 when-to-use and when-not-to-use guidance: omit fileId for a new artifact, pass fileId to revise, use sessionId for follow-ups, reuse operationId only for identical retries, and use create_artifact/update_artifact when files already exist. It also describes the required polling step with get_agent_session, the follow-up show_artifact call, and the separate set_file_sharing call when sharing is requested.

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