declarations_get

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get... Returns...'), which implies non-destructive behavior, and lists the return contents. However, it doesn't disclose response size limits, whether an 'id' not found returns an error vs. empty, authentication requirements, or what 'metadata' and 'error messages' specifically contain. For a getter with zero annotation coverage, the description is helpful but leaves meaningful gaps.

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?

Single sentence, second half enumerates the return payload ('populated data, status, metadata, and error messages'). Zero wasted words, immediately scoped. Front-loaded with the verb and resource.

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 simple 2-parameter getter with 100% schema coverage and no output schema, the description is reasonably complete. It names the payload components. It doesn't explicitly explain the operational semantics (read-only, safe) but a getter's behavior is largely self-evident. Given the complexity level, this is adequate; a slightly richer statement on companyId's env-var override behavior would elevate it further.

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 100%, so both parameters are documented. The description adds value by naming the return payload composition. The description also indirectly clarifies the 'id' is a declaration UUID (matching the schema). 'companyId' is documented in the schema as overriding an env var. The description text doesn't add param-specific detail beyond what's in the schema, but with 100% coverage the baseline of 3 applies and the return-content context bumps it up.

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+resource ('Get a single tax declaration by UUID') and lists what it returns ('populated data, status, metadata, and error messages'). It distinguishes itself from declarations_list (single fetch vs. listing) and from subsequent mutation tools. Slight deduction: it doesn't explicitly contrast with the sibling declarations_get in the broader set, but the single-vs-list distinction is clear from the name and wording.

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 implies this is for retrieving a single declaration by UUID, which contextually separates it from declarations_list. However, there's no explicit 'use this when you have a declaration UUID' guidance, nor 'use declarations_list to find UUIDs first'. No alternative tools are named. Adequate context for a straightforward getter.

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