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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new context: it acts as the org user, refuses arbitrary URLs/SQL/credentials/admin operations, and warns that provider record text is untrusted data rather than instructions (prompt-injection defense). It omits error behavior and any rate/response-size limits for a proxy-style tool, keeping it below 5.

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, front-loaded with the action, with no filler; each sentence carries a constraint, a documentation pointer, or a safety warning. Slightly telegraphic ('no arbitrary URLs, SQL, credentials' is terse to the point of ambiguity), but economical overall.

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?

An output schema exists, so return values needn't be described, and the safety profile is covered by annotations plus the injection warning. However, for an open-ended request-proxy tool with six parameters at 17% schema coverage, the description leaves out endpointId discovery, payload handling, and failure modes — gaps an agent will hit on first use.

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 only 17%: only clientRequestId is documented in the schema, and endpointId, body, query, pathParameters and files are bare. The description adds at most an indirect hint about endpointId ('no arbitrary URLs') but never explains how endpointId is obtained, or how body/query/pathParameters are forwarded, so it does not compensate for the coverage gap.

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?

States a specific verb and resource: 'Execute a discovered GET operation as this organization user' against the SmartShifts organization workforce API. The GET/read framing implicitly separates it from the write siblings (system_execute_write, system_write), but no sibling is named explicitly, so an agent must infer the routing.

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?

'Discovered GET operation' implies the endpoint must first be found via system_search/system_describe, but that prerequisite is never stated. The negative exclusions (no arbitrary URLs, SQL, credentials or platform administration) do usefully bound scope, yet there is no explicit 'use X instead for writes' or when-not guidance.

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