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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered and the description doesn't need to repeat it. It adds modest behavioral context by exposing the GET /odata/v2.0/{company}/Lookup/CompanyRun endpoint and that frequency is a mandatory scoping dimension (one frequency per call). It says nothing about result size, default paging, or what the returned records look like.

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 compact sentences with the purpose front-loaded and the downstream-consumption note second. The raw endpoint string '(GET /odata/v2.0/{company}/Lookup/CompanyRun?frequency=)' is developer-facing filler for an agent and ends in a dangling '?frequency=', which is minor waste but not harmful.

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?

With 100% schema coverage, no output schema, and annotations covering safety, the description supplies what's needed: what is listed, the scoping dimension, and how the results are consumed. It could say more about the shape of the returned period objects (e.g., id vs. label) and that results are capped at 100 per page, but nothing required to invoke it correctly is missing.

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%, so all seven parameters are already documented, setting a baseline of 3. The description adds genuine semantics the schema lacks: the frequency parameter maps to a specific lookup entity (CompanyFrequency/CompanyRun) and the returned values are valid `period` arguments for two named sibling tools, explaining why frequency is required.

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 ('List the payroll runs (periods) of a company for one frequency') and identifies the underlying entity ('the CompanyRun lookup'), which separates it from sibling lookups like payspace_list_payroll_frequencies. An agent knows exactly what comes back: run/period identifiers for a given frequency.

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?

Explicitly tells the agent where the output goes: 'A value goes into the period argument of payspace_list_payroll_components and payspace_list_recurring_components', which makes the call ordering obvious. It does not state when not to use it or that the frequency argument should first come from payspace_list_payroll_frequencies (that routing only appears in the schema), so it stops short of a full 5.

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