read_meta

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful conditional behavior: without a resource it lists every resource with operations; with a resource it details fields, references, and collections. This parameter-dependent behavior is not inferable from annotations and gives the agent a clear expectation of output scope.

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 short sentences, each earning its place: purpose, behavior without resource, behavior with resource, and usage guidance. The conditional behavior is front-loaded after the core purpose, and there is no repetition of schema content. It is compact yet information-dense.

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 one optional parameter, no output schema, and annotations covering read-only safety, the description fully covers what an agent needs: when to call it, what to pass, and how the output varies. No critical information about expected return shape, permissions, or side effects is missing – safety is in annotations, behavior is in description.

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 100% and the parameter description already explains the singular/plural format. The description goes further by explaining the semantic effect: omitting the parameter returns the full catalog, while providing it scopes to that resource's fields and relationships. This adds value beyond the schema by linking the parameter to output behavior.

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 starts with a specific verb-resource pair: 'Describe the Targetprocess resource catalog read from this instance.' It then clarifies the two modes (with/without a resource), which distinguishes it from data-returning siblings like read_query and read_card. The phrase 'Use it before read_query/write_create' further anchors its unique meta-purpose.

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 instruction 'Use it before read_query/write_create' explicitly tells the agent when to call this tool relative to the most relevant alternatives. It implies the recommended workflow without needing to search sibling schemas. This is direct, actionable guidance.

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