Server Quality Checklist

Tool Scores

• legitify.list_pending_requestsC
  2.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral transparency burden. It does disclose that the operation is a non-mutating list and that data comes from a 'local queue.' However, it does not describe return shape, ordering, pagination implications of the limit parameter, or what 'pending' means in this queue context.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single front-loaded sentence with no filler or repetition. It could arguably include more guidance, but as far as conciseness and structure go, it is efficient and respects the reader's attention.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given there is no output schema and no annotations, the description is too thin. It does not explain what the returned list entries look like, what 'local queue' refers to, or how the optional limit behaves. For an agent deciding whether and how to invoke this tool, important context remains missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description needed to compensate for the limit parameter but does not mention it at all. The parameter name and min/max constraints make its purpose somewhat inferable, but the description adds no semantic value beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('list') and resource ('pending attestation requests'), and the parenthetical '(from local queue)' adds operational scope that helps distinguish it from the sibling detail/action tools. It does not explicitly name siblings, but the basic list-vs-detail separation is clear.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives no guidance about when to prefer this tool over alternatives such as get_pending_request_details or review_request. There is no mention of exclusions, prerequisites, or the intended workflow context, so the agent must infer usage from the tool name and siblings.

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

• legitify.submit_attestation_requestB
  3/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It does reveal that a request is submitted and that the resulting status is 'pending', which is useful state information. However, it omits side effects, idempotency, permissions, and error behavior, leaving significant gaps for a mutation-type tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single sentence with no filler; it front-loads the action and includes the most critical return information. Brevity is appropriate even though other dimensions are lacking.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness1/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  This is a complex 9-parameter write tool with no annotations, no output schema, and no parameter documentation in the description. A single sentence about submitting and returning an ID is far from enough for an agent to understand required inputs, workflow relationships, or consequences.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters1/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0% and there are 9 parameters, yet the description mentions none of them. It does not explain required 'title' and 'summary' or the meaning of 'kind', 'evidence', 'spend_usd', 'risk_level', 'requested_action', or other fields, so an agent cannot reliably construct a valid request.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb 'Submit' and a clear resource ('a request for human attestation'), and it states the immediate outcome (attestation_request_id with status=pending). This distinguishes the tool from the sibling get/list/review tools, even without naming them.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance about when to use this tool versus alternatives such as get_attestation_status, list_pending_requests, or review_request. The wording only states what the tool does, not the conditions under which it should be chosen.

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

• legitify.get_attestation_statusB
  3.1/5.0
  Behavior3/5

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

  The description adds a useful behavioral caveat: in MVP, status is 'pending unless manually processed.' With no annotations present, this is meaningful context. However, it does not disclose response format, behavior for unknown IDs, or permissions, which limits transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single sentence with no wasted words. The core operation is front-loaded, and the important MVP caveat is compactly appended in parentheses.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple single-parameter lookup, the description conveys the core operation and an important MVP behavior. However, without an output schema or further explanation of possible status values, an agent is left guessing about the return payload. Sibling guidance is also absent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description names attestation_request_id in prose but adds no meaning beyond the parameter name and type already shown in the schema. With 0% schema description coverage, the description should compensate with format, origin, or usage hints, but it does not.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific operation ('Get status') and a specific resource ('attestation_request_id'), which distinguishes it from submission, review, and policy tools. It doesn't explicitly differentiate from the sibling get_pending_request_details, so it falls just short of a 5.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides no guidance on when to choose this tool over alternatives such as list_pending_requests or get_pending_request_details. The MVP note explains expected behavior, not when to use the tool, so the agent receives no decision support.

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

• legitify.review_requestB
  3.3/5.0
  Behavior2/5

  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 conveys that this is a write operation, but it does not explain whether the receipt is persisted, whether it finalizes or mutates the request, what permissions are required, or what happens to the request after a denied or needs_info decision. This is a significant gap for a review/mutation tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence that contains no filler and captures the core action plus the valid decision values. It is concise without being tautological, though it does sacrifice some behavioral context elsewhere.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a mutation tool with no annotations and no output schema, this description is incomplete. It does not clarify whether the receipt is final, what response the agent should expect, or how to verify the effect (e.g., via get_attestation_status). It covers the required fields but omits broader context needed for safe and confident invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate, but it only explains the two required parameters: the existing attestation_request_id and the decision values. It leaves notes, scope, and reviewed_by to be inferred from their names, with no clarification of formats, optionality, or how they interact with the decision.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb ('Write'), a specific resource ('human attestation receipt'), and the target ('existing attestation_request_id'), with the decision values listed. This clearly separates it from sibling tools like submit_attestation_request or get_attestation_status, so an agent can tell they are different operations.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'for an existing attestation_request_id' implies this tool is used after a request has been created, which is useful context. However, it does not explicitly name sibling tools or state when to use this tool instead of them, so the usage guidance is implied rather than explicit.

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

• legitify.get_policyA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. The verb 'Get' signals a read-only operation and the parenthetical specifies returned content, but it does not disclose auth needs, policy scope, or whether values are static or organization-specific.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is one efficient, front-loaded sentence. It states the operation, resource, and key expected content with no filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a zero-parameter read tool, the description is nearly complete. It tells the agent what information will be returned and implies a non-mutating action. It does not elaborate on what 'default' means or how the policy relates to attestation requests, but sibling context partially fills that gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  There are zero parameters, so the baseline is 4. The description still adds value by explaining what the response contains ('caps, required evidence expectations'), which the empty input schema cannot convey.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb and resource ('Get default policy info') and adds concrete content ('caps, required evidence expectations'). It does not explicitly differentiate from siblings, but its policy focus is clearly distinct from the request-focused sibling tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance about when to use this tool versus alternatives. The description implies a read action but does not state prerequisites, exclusions, or when a sibling tool would be more appropriate.

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

• legitify.get_pending_request_detailsA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the safety burden. 'Fetch' implies a read operation and 'full details ... including evidence' clarifies expected response content, but the description does not address authorization, errors, or behavior if the request is not pending. This is minimally adequate but not rich.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, front-loaded sentence contains all key information: what is fetched, the scope ('pending'), the lookup method ('by id'), and an important content detail ('including evidence'). No filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-parameter read operation with no output schema, the description is nearly complete. It explains the resource, the identifier parameter, and a notable part of the return payload. Slightly more context about response shape or non-pending behavior would make it fully complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0% and the description only says 'by id', which maps to attestation_request_id. This adds the core semantic that the parameter is the identifier of the pending request, but it does not elaborate on format, ownership, or where the id comes from.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Fetch'), a specific resource ('full details for a pending request'), and a lookup key ('by id'), while also calling out ('including evidence'). This clearly separates it from siblings like list_pending_requests and get_attestation_status.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'pending request by id' gives clear context: use this tool when you need full details and evidence for a specific pending request. It stops short of explicitly naming alternatives or stating when-not-to-use, but the usage context is strong enough for an agent to route correctly.

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