Jamf Platform API request

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states the tool is GET-only and has no method or body parameter, discloses that 'flat' style has never returned 200, explains that rawPath requires the tenant segment or returns 400, and notes that Jamf Pro versions are per-resource. This goes far beyond basic safety annotation coverage, providing critical operational expectations.

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 dense but every sentence earns its place: purpose, scope, path construction, versioning, and design rationale. It is front-loaded with the core purpose and read-only guarantee, then progressively details layout options. The length is justified by the tool's generic nature, which requires extensive clarification to be used safely.

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 the tool's complexity (a generic passthrough with multiple path styles, no output schema, and no annotations), the description is exceptionally complete. It covers all key behavioral aspects, path construction, versioning, service segments, and provides strong guidance on when to avoid it. The rationale for why writes are excluded (unreviewable) adds crucial context for safe usage.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies the 'tenant' default, explains that 'classic' fills the tenant automatically and omits the version segment, details rawPath verbatim behavior, and notes service can be multi-segment (e.g., 'ddm/report'). This transforms the parameter descriptions from raw definitions into actionable usage rules.

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 it makes authenticated GET requests against any Jamf Platform API Gateway endpoint, covering both Jamf Pro and Classic APIs. It explicitly distinguishes itself from the typed sibling tools by emphasizing that writes go through named typed tools, not this passthrough. The READ-ONLY BY DESIGN statement and mention of 300+/500+ endpoints make the tool's purpose and scope 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?

Provides explicit guidance on when to use this tool (for any GET request against the gateway, including endpoints not covered by typed siblings) and when not to (writes must use named typed tools). It also offers detailed usage instructions for path styles (tenant vs. classic vs. flat), rawPath requirements, service segment composition, and version selection, making it clear how to choose alternatives like style 'classic' over rawPath. The reference to JPM-0007 suggests additional context.

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