zms_get_metadata

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only'. It adds useful context beyond annotations by specifying 'full record' and the ZSCALER_CUSTOMER_ID requirement. No contradiction exists, and the description does not hide side effects or permissions issues.

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, front-loaded, and scannable. The only minor redundancy is restating 'Read-only' when readOnlyHint=true is already in the annotations, but overall every sentence serves a purpose and the text is not bloated.

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?

Given zero parameters, an output schema, and a read-only annotation, the description is nearly sufficient. It explains what the metadata covers and notes the required customer ID. Slightly more detail about what 'resource-level events' means would help, but the tool is simple enough that this is adequate.

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?

The input schema has zero parameters, so the baseline is 4. The description adds a meaningful prerequisite, ZSCALER_CUSTOMER_ID, which is valuable since the schema itself is empty. There are no parameter details to elaborate on, so this score is appropriate.

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 operation: 'Get ZMS resource event metadata (full record)', and clarifies the scope as 'resource-level events available in the deployment'. This is clear and mostly distinguishes the tool from sibling ZMS list/get tools, though 'full record' remains slightly vague.

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 gives clear context for when to use the tool: when metadata about available resource-level events is needed. It also highlights the ZSCALER_CUSTOMER_ID prerequisite. It does not name alternatives or exclusions, but for a zero-parameter metadata getter that is acceptable.

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