Point scan

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the mutation-ish, non-idempotent, external-facing profile is covered structurally. The description adds one genuinely useful detail -- that target_sys_id and target_table are effectively mandatory despite the schema listing zero required parameters. It omits the async nature implied by 'Initiate' (i.e., that results are later polled via servicenow_instance_scan_progress) and says nothing about side effects or scope of the scan.

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 purpose sentence is front-loaded, which is good, but 'based on the provided parameters' is pure filler and the Sphinx-style :param/:type/:return/:raises block is boilerplate that spends four lines documenting two of 43 parameters. It is short overall, so there is no bloat, but the allocation of space is poor.

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?

For a 43-parameter tool with no output schema and a 0%-covered schema, the description is far too thin: it does not explain the scan's async lifecycle, what a point scan actually covers, or the role of any optional parameter. It resolves only the mandatory-parameter question, leaving an agent unable to invoke anything beyond the two-field minimal form.

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% across 43 parameters, so the description carries the full burden and fails it -- only target_sys_id and target_table are explained, leaving ~41 parameters (scope, scan_type, plugin_id, packages, repo_url, update_set_id, etc.) completely undefined. The two documented params are the critical ones, which earns some credit, but the vast parameterization of this tool remains opaque.

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 names a verb ('Initiate') and resource ('point instance scan'), which is a real purpose statement rather than a tautology. However, 'point scan' is unexplained jargon and the description never distinguishes it from the sibling scan tools (servicenow_full_scan, servicenow_suite_scan, servicenow_combo_suite_scan), so an agent cannot tell which scan variant to pick from this text alone.

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?

There is no when-to-use guidance whatsoever: no conditions selecting this over a full or suite scan, no prerequisites, no mention of the time/scope tradeoff that would justify a 'point' scan. The only contextual hint is the MissingParameterError clause, which is not usage guidance.

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