cipp_get_secure_score

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the underlying Graph call, that top is sent with NoPagination so it truncates the series rather than just sizing a page, that a result filling the limit carries a warning about older readings, and that an empty collection means 'no reading' rather than a score of zero. Those are exactly the traps an agent would otherwise fall into.

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?

Front-loaded with the verb and resource, then layered detail; every clause carries information. It is a single dense paragraph with the caveats strung together, which makes it slightly harder to scan than a short bulleted set of constraints, but there is no filler.

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 only two parameters, no output schema, and no annotations covering return shape, the description does the heavy lifting: it describes the returned fields and their ordering (lowest completion first, newest-first history), the truncation caveat, and the empty-versus-zero distinction. An agent has everything needed to call it and interpret the response.

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, and the description adds a genuine semantic point: top is combined with NoPagination so it limits the returned series, not Graph's page size, plus confirmation that allTenants is rejected. Most of the remaining detail (default 7, max 90, tenant ID form) duplicates what the schema already states, so it is additive but not fully beyond the schema.

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 opening sentence names a specific verb (read, live), the exact resource (a tenant's Microsoft Secure Score), and then enumerates what comes back: points, percentage, comparisons on 'AllTenants'/'TotalSeats' bases, control-level achievement, and newest-first daily history. It is clearly distinguishable from the sibling cipp_list_secure_score_controls, and the closing line 'Changing a control's state is not this tool' rules out another nearby interpretation.

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?

It states the operational context (there is no dedicated CIPP list endpoint; this wraps ListGraphRequest against security/secureScores) and explicitly rules out allTenants because the estate view lives in the nightly cache. That is strong when/when-not guidance, but it never names the tool an agent should call instead for the estate view or for control-state changes, leaving the agent to infer the alternative.

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