Search Intune policies

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description implicitly supports (search operation). Beyond annotations, the description adds valuable behavioral context: internal Graph /beta request generation, that every record returns id+categoryId, that display names are non-unique warranting caution, and that isAssigned values are 'Graph-reported hints' that need reconciliation. Also notes results can be RBAC-filtered. This adds meaningful context beyond the structured fields.

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?

Four tight sentences, each earning its place: scope/purpose, output-chaining instruction, uniqueness caveat, and hint-reconciliation warning. No filler, no repetition of schema. Dense and front-loaded.

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?

This is a search tool with 5 optional params, generous annotations (read-only, open-world, idempotent), and a rich description. The output schema exists to document return format. The description covers purpose, downstream usage, data-quality caveats (non-unique names, Graph hints), and RBAC implications. Complete for an open-ended search function with good structured data backing.

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 0%, so the description must compensate for the 5 undocumented parameters. The description effectively explains the query/category semantics by establishing that search spans policy AND application categories, enumerating awareness of category types (configurationPolicy, deviceConfiguration, compliancePolicy, application, appConfiguration in the enum). It also explains the meaning of returned values (id, categoryId, isAssigned) which illuminates result processing rather than input params directly, but provides meaningful operational context.

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 verb+resource ('Searches supported Intune policy and application categories through internally generated Microsoft Graph /beta requests') and clarifies scope ('supported...categories'). It distinguishes from sibling get_policy_assignments by explicitly instructing to pass id/categoryId as policyId/category, and mentions RBAC filtering which differentiates it in search space.

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 clearly explains when to use this tool (searching policies/apps) and connects it to the downstream sibling get_policy_assignments by prescribing how to pass returned values. It warns about non-unique display names and reconciling isAssigned hints, giving selection caution. It doesn't explicitly name alternatives like list_unassigned_policies or list_all_device_assignments, but the chaining guidance is strong.

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