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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the 'reusable' qualifier, suggesting that this list may contain only questions that are reusable across job postings, which is useful context beyond the annotations. However, it does not explain pagination behavior or that the list might be large. Since the annotations cover the safety profile, this is a reasonable score, but the description could have added more behavioral detail.

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, concise sentence that is front-loaded with the key action and resource. It is efficient and not verbose. The sentence is easy to read and has no unnecessary words. While it could have included more information, the conciseness itself is well-executed.

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 that the tool has 3 parameters (all optional) and no output schema, the description needs to explain the purpose and scope of those parameters. It fails to do so. It also does not clarify what a 'question catalog' means in this context or whether company_id is required to filter by company. For a list operation that could be paginated, the lack of parameter semantics is a major gap. The description is too minimal to ensure correct invocation.

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?

The schema description coverage is 0%, meaning the description provides no information about the three parameters: page, size, and company_id. The description does not even hint at pagination (page and size) or the requirement for company_id to scope the catalog. Given that there are 3 parameters with no documentation in either the schema or the description, the description fails to compensate for the low coverage. This is a significant gap that could lead to incorrect calls.

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 'List the reusable question catalog of the company' clearly identifies the verb (list) and resource (reusable question catalog), but it does not distinguish from the related tools like hires_list_question_types or hires_get_question. The term 'catalog' is somewhat ambiguous; it could refer to a list of question objects or a collection of question types, and it doesn't explicitly clarify whether it lists all questions or just the reusable ones. There is no mention of pagination or filtering options that would differentiate it from other list tools.

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 no guidance on when to use this tool versus alternatives such as hires_get_question (to fetch a specific question) or hires_list_question_types (to list available question types). It does not specify that this tool is for listing a catalog of questions, which is distinct from the type enumeration. There is no mention of when not to use it or any prerequisites. The intended use case is implied but not explicit.

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