manage_security_baselines

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

With no annotations, the description carries the full burden. 'View' clearly implies read-only operations, and the three action descriptions reinforce this. It also discloses that get_status requires a profile_id. It doesn't explicitly state 'no changes are made' or mention permissions, but for a read-only tool the behavior is adequately conveyed.

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?

The description is concise, with a summary line followed by a simple bulleted action list. It avoids unneeded words, though the action list slightly rephrases the summary. Overall, it is well-structured 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?

The tool has multiple actions and three parameters, and the description explains each action's purpose. An output schema exists, so return values are covered. The main gap is the undocumented top parameter, but this does not significantly hinder the agent's ability to use the tool correctly for its core reading operations.

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 0%, so the description must compensate. It fully explains the action parameter by listing valid values with meanings, and clarifies that profile_id is used for get_status. However, the top parameter is left undocumented in both the schema and description, creating a gap for the agent.

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 'View Intune security baseline templates and deployed profiles' and enumerates three specific actions (list_templates, list_profiles, get_status), clearly identifying the resource and operations. This distinguishes it from sibling manage_* tools which target other Intune domains.

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 opening line provides clear context: use this tool when needing to view security baseline templates/profiles. However, it does not explicitly mention alternatives or exclusions, though the sibling tool names make the domain scoping obvious. A more explicit 'use X for Y' would raise this to a 5.

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