Create and send a Document Request

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

With readOnlyHint=false, the description appropriately implies a mutation. It goes beyond annotations by disclosing the exact behavior: the email is sent immediately to the specified recipient only, and the client uploads via a secure link. It also warns about error behavior, naming the created request if email fails, which is valuable context not available from the schema or 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 concise, front-loaded with the primary use, and covers both the main action and edge cases in just three sentences. It could be slightly more structured (e.g., bullet points for parameters), but it is efficient and to the point.

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 description is complete given the schema and output schema absence. It explains the core purpose, the recipient scope, the one-step behavior, and error handling. The schema already covers parameter details, so nothing essential is missing for an agent to invoke the tool correctly.

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?

The schema has 100% description coverage for all parameters, so the description does not need to add much, and it does not. It explains the purpose of recipient_email, deadline, and documents in the context, but doesn't add detail beyond what the schema already provides. However, note that 3 parameters are not required (title, message, recipient_name) and the description mentions 'optional title and a message', which adds slight contextual meaning. Yet because the schema descriptions already fully cover all parameters, the description adds minimal value, so it sits at baseline 3.

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?

This description clearly states what the tool does: it creates and sends a Document Request in one step. The verb 'create and send' is specific, and it identifies the resource (Document Request) and the action (emailing it). The title and description effectively differentiate it from siblings like 'get_request' or 'download_documents', which have different purposes.

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 explicitly tells the agent when to call this tool: when the Professional wants to ask a Client for documents. It also specifies the one-step nature (create and send) to avoid leaving requests unsent Poisson. However, it does not explicitly mention when not to use it or alternative tools (e.g., if the Professional wants to draft without sending, such as with 'request_replacement'), so it is slightly less than a 5.

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