outlook_create_task

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

Goes well past the readOnlyHint=false / destructiveHint=false annotations by disclosing a silent-failure mode ('Graph silently drops a reminder that has no time') and a defaulting side effect (falls back to the default list). It also flags the ambiguous relative-offset parsing where a bare '7d' means seven days ago, which is exactly the kind of trap an agent would otherwise hit.

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?

Purpose is front-loaded, followed by a compact example and four short, high-value notes; each line carries distinct information. The example line is mildly redundant with the notes but earns its place by showing argument names in use.

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 7-parameter create tool with a nested object and no output schema, the description covers the risky and ambiguous parameters well. The gap is recurrence, an untyped nested object with no explanation anywhere in the definition, and no hint of what the call returns.

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?

With 0% schema description coverage the description must carry the load, and it does for due (ISO 8601 or relative offset), importance (low/normal/high), reminder (requires due), and list_id (default-list fallback). It documents neither the shape of the nested recurrence object nor anything about body beyond 'optional body', leaving two of seven parameters thin.

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?

States a specific verb and resource ('Create a Microsoft To Do task') and enumerates the optional fields, which cleanly separates it from the sibling mutators outlook_update_task, outlook_complete_task, and outlook_delete_task. An agent can identify the right tool without opening the schema.

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?

Provides clear operating context: list_id omission falls back to the user's default list, and reminder=True requires due. It does not explicitly state when to prefer outlook_update_task or outlook_add_checklist_item instead, so the routing guidance is implied rather than spelled out.

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