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

Annotations already convey mutation (readOnlyHint=false, destructiveHint=true), so the description is not required to restate that. It adds valuable behavioral context beyond annotations: writes land in a shared AIsa workspace, records become visible/editable by others, and there is no per-caller isolation. This is meaningful side-effect disclosure that helps an agent understand cross-caller impact.

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?

Three sentences with no filler. The primary purpose is front-loaded, followed by the most important parameter sourcing detail and then the shared-workspace caveat. Every sentence earns its place and the description is compact.

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 well-rounded for a mutation tool with an output schema: it names the entity, sourcing guidance, and important cross-caller side effects. It falls slightly short of 5 because it does not mention the bulk-create alternative and leaves type/status value constraints entirely to the sparse schema descriptions.

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 coverage is 100%, so the baseline is 3, but the description adds useful semantics by pointing to get_apollo_users_search as the source of owner IDs. It also clarifies optional linking to contact or account. However, 'account' is mentioned without a corresponding account_id parameter in the schema, and both type and status remain minimally described.

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 states a specific action (create), resource (task), and key scoping details (assigned to a workspace user, optionally linked to contact or account). It also names the source for owner IDs, which differentiates this from other post_apollo_* tools. This is immediately interpretable by an agent.

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 gives clear context for using this tool: create a single task, optionally linked to a contact or account, with owner IDs from get_apollo_users_search. However, it does not explicitly contrast it with siblings like post_apollo_tasks_bulk_create or state when not to use it.

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