Get cmdb instance

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds that the response contains attributes and relationship information and is parsed into a Pydantic model, but it does not describe pagination, authentication needs, or other operational behavior.

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 short and front-loads the core purpose in the first sentence. The remaining docstring-style parameter notes are compact, though the two undocumented parameter types add little value for a 12-parameter tool.

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 tool with 12 parameters, 0% schema description coverage, and no output schema, the description is not complete enough. It explains only two parameters and gives a brief return summary, leaving most inputs and pagination/query behavior unaddressed.

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 carry the burden, but it documents only className and sys_id out of 12 parameters. Ten parameters, including data, source, attributes, rel_sys_id, sysparm_limit, sysparm_query, sysparm_offset, api_parameters, inbound_relations, and outbound_relations, remain undocumented in both schema and description.

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 clearly states a specific verb and resource: returns attributes and relationship information for a specified CI record. It does not, however, distinguish this tool from close siblings such as servicenow_get_cmdb_instances or servicenow_get_cmdb, leaving the agent to infer which one to use.

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 guidance on when to use this tool versus alternatives like servicenow_get_cmdb_instances or servicenow_get_cmdb. The description only provides parameter docstrings, not usage context or exclusions.

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