p6_query_activities

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

Annotations already declare this a safe, idempotent read, so the safety profile is covered. The description adds meaningful behavior beyond that: sort order with the 'actual, else early' start tiebreak, inclusive-date semantics for finish_before, and the fact that durations/float are expressed in each activity's own calendar days. It does not discuss paging cost or filter-combination behavior, so 4 rather than 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?

No filler sentences and the page shape plus sort order are front-loaded, which is the right ordering for a search tool. The prose is dense and slightly run-on in the code_value/code_type stretch, but every clause adds operative information.

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 properly documents the return envelope {total, offset, returned, next_offset, rows} and how to page via offset. Combined with the filter semantics, an agent has enough to call it correctly, though the three undocumented filter params and the unspecified param interactions leave a small gap.

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 only 21% across 14 params, so the description carries most of the burden and largely does: it explains status enum values, date format and inclusivity, the WBS scoping caveat, code_type precedence (project type beats EPS/global), code_value path/short-name/name resolution, include_child_codes, code_filter output, and fields= semantics. It leaves code_prefix, name_contains, and max_total_float_days entirely unexplained, which keeps it off a 5.

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+resource ('Search activities') and immediately defines the return envelope and sort order. It also differentiates itself from siblings by name, pointing at p6_list_wbs for whole-WBS-branch filtering and contrasting with p6_get_activity's single-activity scope.

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?

Gives a concrete routing rule: wbs_name_contains only matches the activity's own WBS node, so for a branch use p6_list_wbs or an activity-code filter. It also explains when to reach for code_type/code_value vs name filters. It stops short of explicit when-not guidance against p6_get_activity or p6_lookahead, so not a full 5.

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