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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description still adds meaningful behavioral context beyond that: the count is performed 'without creating a broadcast,' which confirms no persistent artifact is produced. It does not describe response shape or any rate/volume limits, keeping it below 5.

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 short sentences with the core purpose front-loaded and every clause carrying information. Slight redundancy: the omit-or-pass-{} default for segment_query is already stated verbatim in the schema description, so one sentence partially duplicates structured data.

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?

With no output schema, the description usefully signals the return value ('Count how many contacts match'), and the nested-object parameter is explained via cross-reference. For a one-parameter, read-only tool this is close to sufficient; only the exact return shape (bare integer vs. object) is left implicit.

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% and the single nested parameter carries its own example, so the baseline is 3. The description adds value by cross-referencing 'the same segment_query shape used by meisa_create_broadcast' and restating the omit-or-{} default behavior, giving the agent an additional mental model for authoring the nested object.

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 ('Count how many contacts match a segment query') and immediately separates itself from the write path with 'without creating a broadcast.' An agent can distinguish it from meisa_create_broadcast and meisa_search_contacts without opening any 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?

'Use this to size an audience before building a campaign' gives clear context for when to reach for it, and the reference to the segment_query shape used by meisa_create_broadcast routes the agent to the related tool. It stops short of an explicit when-not statement (e.g., 'do not use this to actually send'), which would make it a 5.

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