beel_get_representation

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavior: the return of a NOT_STARTED state with HTTP 200, and the safety for polling. Additionally, the parameter description within the schema (which is part of the input schema) reveals authentication behavior: a NIF not reachable returns 403, and nonexistent NIFs also return 403 to avoid disclosing existence. This goes well beyond what annotations convey and is a substantial contribution to transparency.

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 concise and well-structured. It starts with the purpose, then explains the important non-error behavior, and ends with the endpoint. Every sentence adds value, and there is no redundancy with the annotations or schema. It is front-loaded with the main purpose, and the endpoint line is a helpful technical detail.

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?

Given there is no output schema, the description provides an adequate overview of the return states and the safe polling behavior. It does not detail the exact JSON response structure, but the states listed (NOT_STARTED, generated, signed, submitted, accepted, cancelled) give the agent enough to interpret results. The tool has a single parameter with thorough documentation, and its read-only/idempotent nature is declared. The description is complete for practical usage, though a mention of the response fields would make it slightly better.

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%, and the company_id parameter description is already very rich: it explains the NIF is the only context, the account is derived from it, the header is ignored, and 403 behavior for unreachable/nonexistent NIFs. The tool description itself adds no additional parameter semantics beyond what the schema provides. Since the schema covers everything, a baseline score of 3 is appropriate.

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 tool's purpose: it returns the state of AEAT fiscal representation for a company (NIF), enumerating the specific states (generated, signed, submitted, accepted, cancelled). The verb 'returns the state' is specific and the resource is the representation. It implicitly distinguishes itself from sibling tools like generate_representation and download_representation_document by focusing on the state query.

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 provides clear usage guidance by stating that a company that never started the process is not an error and that polling is always safe. This tells the agent when it is appropriate to call the tool repeatedly. However, it does not explicitly name alternative actions like generate or download when the state indicates a certain stage, leaving some inference for the agent. It gives context but not explicit when-not-to-use guidance.

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