swsd_get_catalog_item

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

Beyond the readOnly/idempotent annotations, the description richly discloses the response behavior: it returns the item plus a `variables` array describing the form schema, including `id`, `name`, `kind`, and `options`. It even explains that options are newline-separated and that the full top-level item is available to power users. This gives the agent a concrete mental model of what the tool does and returns.

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 only a few sentences and every sentence earns its place: main action first, then how the variables work, then parameter/return guidance for power users. It is dense yet readable, with no filler or duplication of the schema.

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 a single well-documented parameter, strong annotations, an available output schema, and rich behavioral description, the definition is complete. It even covers the downstream integration with create-user service request and explains the detail an agent needs to make sense of the response.

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 already fully documents the only parameter with 100% coverage, including the fact that the id comes from swsd_list_catalog_items. The tool description adds general context about id being used for catalog lookup, but does not materially improve on the schema's own description. Baseline 3 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 clear verb and resource: 'Get a single SWSD catalog item by id', and adds important scoping by saying 'single' rather than list, distinguishing it from list_catalog_items. It also clarifies the tool's unique value through the `variables` form-schema content, making its purpose unmistakable.

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 concrete usage context: the variables tell you which fields to populate when submitting a service request, and each variable id should be passed to the create-service-request tool as `custom_field_id`. It does not explicitly say when not to use it versus list_catalog_items, but the 'by id' scoping plus the creation workflow guidance is enough for an agent to select it appropriately.

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