get_schedule

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

No annotations are provided, so the description carries the burden of behavioral disclosure. The description states it's a GET mapping and readonly tier, which implies a read operation. However, it doesn't describe what's returned (schedule structure, availability format), whether employee_ids is required for filtering, or any response shape. The readonly nature is only conveyed via the tier note rather than explicit behavior description.

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?

Two sentences, efficient and front-loaded. The endpoint mapping and tier annotation add useful context without bloat. Could perhaps mention the filter param but the description is appropriately concise for its scope.

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 read tool with no output schema, the description gives the endpoint and scope but not return format, filtering behavior of employee_ids, or pagination. Given the moderate complexity (read-only schedule retrieval), the description is somewhat sparse but adequate for a straightforward GET operation with two required date params.

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 67% (2 of 3 params have descriptions). The description adds 'date range' context which maps to start_date and end_date, and both already have 'ISO 8601 date' descriptions in the schema. The employee_ids parameter's semantics (whom to filter by) is inferable from the name but not described in either schema or description. Baseline 3 is appropriate given moderate schema coverage.

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 the verb (get), resource (technician schedules and availability), and scope (for a date range). It also maps to the underlying endpoint (GET /schedule). However, it doesn't explicitly distinguish from sibling tools like get_appointment or list_job_appointments, though those are clearly different resources, so purpose is clear.

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?

No when-to-use guidance is provided. The description doesn't mention when a date range is required, whether employee_ids is optional filtering, or how this relates to appointment/schedule tools as alternatives. The tier marker '[tier: readonly-owner]' hints at permission context but no explicit usage context or exclusions are given.

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