taxme_get_fields

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

With no annotations, the description carries full burden. It discloses truncation behavior (limit, default 60), that the reply reports omitted fields, the meaning of 'locked', and that taxme_fill still sees all fields. This goes well beyond a simple 'list fields' statement.

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 a single information-dense and front-loaded sentence, but it becomes a bit run-on with parentheticals and semicolons. Every clause earns its place, yet splitting into two sentences would improve readability.

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?

Despite having no output schema, the description fully covers what the tool returns (list of fields with specific attributes), the limit behavior, the locked concept, and the interaction with taxme_fill. This is complete for a low-complexity read-only tool with one parameter.

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% for the single 'limit' parameter, so baseline is 3. The description adds behavioral semantics: limit causes truncation and the reply states how many were left out, which the schema alone does not convey.

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 starts with 'List interactive fields on the current page' – a specific verb and resource. It enumerates the field attributes (id, type, value, label, context, radio group name, locked) and distinguishes itself from siblings by referencing taxme_fill behavior.

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?

Usage is implied (use this to see fields on the current page) but no explicit when-to-use or alternatives are given. The mention that taxme_fill resolves against every field hints at a workflow but does not state 'use this before filling' or contrast with sibling tools like taxme_snapshot.

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