Server Quality Checklist

Tool Scores

• issue_credentialA
  4.2/5.0
  Behavior3/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. It discloses that the tool returns 'a signed JWT plus claims including the task tree ID,' which adds useful behavioral context about the output format. However, it doesn't mention authentication requirements, error conditions, rate limits, or whether this is a write operation (though 'issue' implies creation). The description adds some value but leaves gaps for a credential-issuing 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 appropriately sized and front-loaded: the first sentence states the core purpose, the second provides usage context, and the third gives output and sibling guidance. Every sentence earns its place with no wasted words, making it efficient and well-structured.

  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?

  Given the complexity of a credential-issuing tool with no annotations and no output schema, the description does well by explaining the purpose, usage context, output format (JWT with claims), and sibling relationship. However, it lacks details on error handling, security implications, or what happens on failure, which would be helpful for completeness. The high schema coverage helps offset some gaps.

  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 description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain scope format or TTL defaults). With high schema coverage, the baseline is 3, and the description doesn't compensate with extra semantic information.

  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 clearly states the specific action ('Issue a new root credential'), resource ('for a task'), and distinguishes it from sibling tools by explicitly mentioning 'use delegate_credential for child agents instead of issuing multiple unrelated root credentials.' This provides a precise verb+resource combination with sibling differentiation.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('at the start of a workflow when an orchestrator or top-level agent needs explicit scoped authority tied to a human user and instruction') and when not to use it ('use delegate_credential for child agents instead'). It names the alternative tool and specifies the context clearly.

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

• check_revocationA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: returns a 'small revocation status object' and specifies that 'network or API failures are returned as MCP errors.' This covers key behavioral aspects like return format and error handling, though it doesn't mention rate limits, authentication requirements, or caching behavior.

  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 efficiently structured in two sentences with zero wasted words. The first sentence establishes purpose and usage guidelines, while the second covers behavioral aspects. Every phrase adds value, and the information is appropriately front-loaded with the core functionality.

  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 single-parameter read operation with no annotations and no output schema, the description provides strong contextual completeness. It covers purpose, usage guidelines, behavioral aspects (return format and error handling), and distinguishes from sibling tools. The main gap is the lack of output schema details, but the description compensates by describing the return as a 'small revocation status object.'

  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 description coverage is 100%, so the schema already fully documents the single 'jti' parameter. The description adds no additional parameter semantics beyond what's in the schema (which defines it as 'Credential unique ID'). The baseline score of 3 is appropriate when the schema does all the parameter documentation work.

  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 clearly states the specific action ('check whether...is currently revoked'), identifies the resource ('credential JTI'), and distinguishes this from sibling tools by specifying it's for 'one-time revocation lookup' rather than verification or other credential operations. It explicitly contrasts with signature/expiry/task history verification.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('when you already know the credential ID' and 'for a one-time revocation lookup') and when not to use it ('does not verify signature, expiry, or task history'). It clearly differentiates this from verification and other credential management operations among the sibling tools.

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

• delegate_credentialA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the server enforces scope subsetting, and it implies a mutation operation (creating a child credential). However, it lacks details on permissions, rate limits, or error handling, which would be beneficial for a credential management 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 concise and front-loaded, with two sentences that directly address purpose and usage. Every sentence adds value: the first defines the action and context, and the second provides critical behavioral and alternative guidance. There is no wasted text 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?

  Given the complexity of credential delegation and the lack of annotations and output schema, the description does a good job covering purpose, usage, and key behavior. However, it omits details on return values (e.g., what the child credential looks like) and potential side effects, which would enhance completeness for this type of tool.

  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?

  The input schema has 100% description coverage, providing baseline documentation for all parameters. The description adds minimal semantic context by mentioning 'child_scope' as a 'subset of the parent' and 'ttl_seconds' as 'Child token lifetime,' but this mostly reiterates schema info. It doesn't explain format specifics (e.g., JWT structure) beyond the schema.

  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 clearly states the specific action ('Create a narrower child credential from an existing parent credential') and the resource involved. It explicitly distinguishes this tool from its sibling 'issue_credential' by explaining when to use each, making the purpose distinct and well-defined.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('when handing work to a sub-agent or isolated step that should receive only a subset of the parent scope') and when not to ('if you need the original root authority, use issue_credential instead'). It names the alternative tool, offering clear context for selection.

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

• deny_approvalA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's action ('Reject', 'changes the approval status'), outcome ('returns the final rejected state'), and system impact ('in Attest'), though it lacks details on permissions, error handling, or side effects. No contradiction exists.

  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 concise and well-structured, with two sentences that front-load the core action and usage context. Every sentence adds value: the first defines purpose and key constraint, the second provides usage guidelines and outcome. No wasted words.

  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?

  Given the tool's complexity (a mutation with no annotations or output schema), the description is fairly complete. It covers purpose, usage, and behavioral outcome, but lacks details on error cases, permissions, or return format specifics. It compensates well for the absence of structured fields but has minor gaps.

  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 description coverage is 100%, so the schema already documents the 'challenge_id' parameter fully. The description does not add any additional semantic context about the parameter beyond what the schema provides, such as format examples or sourcing. Baseline 3 is appropriate as the schema handles the heavy lifting.

  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 clearly states the tool's purpose with specific verbs ('Reject', 'changes the approval status') and resource ('pending approval challenge'), distinguishing it from sibling tools like 'grant_approval' (approve) and 'get_approval' (inspect). It explicitly mentions what it does not do ('without minting a child credential'), adding precision.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('when a human declines the requested access') and when not to ('for passive inspection use get_approval instead'), naming a direct alternative. This helps the agent choose correctly between active rejection and passive inspection.

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

• get_approvalA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it's a read operation (implied by 'Fetch'), returns specific data ('approval record from Attest'), handles errors ('invalid or unknown challenge IDs will surface as an MCP error response'), and clarifies it doesn't poll. However, it doesn't mention rate limits, authentication needs, or whether the operation is idempotent, leaving some gaps.

  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 efficiently structured in two sentences: the first states the core purpose and usage context, the second covers returns and error handling. Every sentence adds value with zero redundant information, making it easy to parse and understand quickly.

  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 single-parameter read tool with no output schema, the description is quite complete: it explains purpose, usage context, return values, and error behavior. The main gap is lack of output format details (what fields the 'approval record' contains), but given the tool's simplicity and clear annotations-like disclosure in the description, it's largely adequate.

  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 description coverage is 100% (the single parameter 'challenge_id' is fully described in the schema as 'Approval challenge ID'), so the baseline is 3. The description adds no additional parameter information beyond what the schema provides, but it does reinforce the parameter's purpose in context ('by challenge_id').

  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 clearly states the specific action ('Fetch the current status'), resource ('one approval challenge by challenge_id'), and scope ('one-time status check'), distinguishing it from siblings like request_approval (initiates) or list_tasks (lists multiple). It explicitly mentions what it returns ('approval record from Attest') and error handling for invalid IDs.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('after request_approval when you need a one-time status check') and when not to use it ('does not perform repeated polling by itself'), clearly differentiating it from potential polling alternatives. It also implicitly distinguishes from siblings like grant_approval or deny_approval by focusing on status checking rather than decision-making.

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

• get_audit_trailA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden. It discloses that the tool 'does not change state' (indicating read-only behavior) and returns 'raw Attest audit events', which adds context about output format. However, it lacks details on error handling, rate limits, or authentication needs, leaving some behavioral aspects unspecified.

  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 front-loaded with the core purpose, followed by usage guidelines and behavioral notes in two efficient sentences. Every sentence earns its place by adding critical information without 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?

  Given the tool's complexity (fetching audit data), no annotations, and no output schema, the description is mostly complete: it covers purpose, usage, and read-only behavior. However, it doesn't detail the structure of returned 'raw Attest audit events', which could be important for an agent to interpret results, leaving a minor gap.

  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 description coverage is 100%, so the schema already documents the single parameter task_id. The description adds minimal value by implying task_id is needed for fetching the audit trail, but doesn't provide additional syntax or format details beyond what the schema states. Baseline 3 is appropriate when schema does the heavy lifting.

  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 clearly states the verb 'fetch' and the resource 'full audit event chain for a single task tree', distinguishing it from siblings like list_tasks (which discovers tasks) and other tools that perform actions like issue_credential or revoke_credential. It specifies the scope as detailed chronology for specific events.

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

  Usage Guidelines5/5

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

  Explicit guidance is provided: 'Use this when you already know the task_id' and 'use list_tasks first if you need to discover candidate tasks'. This clearly defines when to use this tool versus the alternative (list_tasks) and sets prerequisites.

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

• get_evidenceA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a read-only operation ('does not mutate any task state'), describes the output ('full evidence packet produced by Attest'), and implies it's for verification purposes. However, it doesn't mention potential limitations like rate limits or authentication requirements.

  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 efficiently structured in two sentences that each serve distinct purposes: the first defines the tool's purpose and usage guidelines, the second clarifies behavioral aspects. There's no wasted language, and key information is front-loaded.

  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 single-parameter read operation with no output schema, the description provides good context about what the tool returns and its non-mutating nature. However, without annotations or output schema, it could benefit from more detail about the evidence packet format or potential error conditions.

  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?

  The schema description coverage is 100%, so the schema already documents the single 'task_id' parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, maintaining the baseline score for high schema coverage.

  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 clearly states the specific action ('Fetch') and resource ('signed evidence packet for one task tree'), distinguishing it from sibling tools like 'get_audit_trail' which provides a different type of output. It precisely defines what the tool does without being vague or tautological.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('when you need a portable proof artifact for compliance review, incident analysis, or independent verification') and provides a clear alternative ('use get_audit_trail for a simpler raw event timeline'). This gives the agent specific guidance on tool selection.

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

• grant_approvalA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: that this is a state-changing operation ('This changes system state'), that it consumes resources ('consumes the pending approval'), and what it returns ('returns the delegated token that should be used for the gated step'). It doesn't mention error conditions or rate limits, but covers the essential mutation behavior well.

  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 efficiently structured in three sentences that each serve distinct purposes: stating the action, providing usage guidelines, and describing behavioral consequences. There's no wasted text, and the most critical information (the tool's purpose) is front-loaded in the first sentence.

  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 state-changing tool with no annotations and no output schema, the description does an excellent job covering the essential context: purpose, usage guidelines, behavioral impact, and return value guidance. It doesn't describe the exact format of the returned token or error scenarios, but given the tool's complexity and lack of structured metadata, it provides substantial contextual completeness.

  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 description coverage is 100%, so the schema already documents both parameters adequately. The description doesn't add any additional parameter-specific information beyond what's in the schema descriptions. It mentions the parameters contextually ('their OIDC identity token' references id_token), but doesn't provide new semantic details. This meets the baseline for high schema coverage.

  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 clearly states the specific action ('Approve a pending approval challenge and mint the HITL-authorized child credential'), identifies the resource ('pending approval challenge'), and distinguishes it from sibling tools by explicitly naming an alternative ('for status checks use get_approval instead'). This provides a complete and differentiated purpose statement.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('only when a human approver has already authenticated and you have their OIDC identity token') and when not to use it ('for status checks use get_approval instead'). It clearly names an alternative tool and specifies prerequisites, making usage context unambiguous.

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

• list_tasksA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's a read operation, returns task summaries only, does not mutate task state, and operates on the authenticated organization. However, it lacks details on rate limits, pagination, or error handling, which would be helpful for a list operation.

  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 efficiently structured in three sentences: the first states the core functionality, the second provides usage guidelines, and the third clarifies behavioral aspects. Every sentence adds value with zero wasted words, making it easy to parse quickly.

  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 list operation with no annotations and no output schema, the description does well by clarifying the read-only nature and return type. However, it could be more complete by mentioning typical response structure or any limitations (e.g., maximum limit values, default sorting). The absence of an output schema increases the need for return value description.

  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?

  The schema description coverage is 100%, so the schema already fully documents all four parameters. The description mentions the optional filters (user, agent, status, limit) but doesn't add meaningful semantic context beyond what the schema provides. This meets the baseline for high schema coverage.

  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 clearly states the verb ('List') and resource ('Attest task trees for the authenticated organization'), specifies the scope ('recent'), and distinguishes it from sibling tools by mentioning when to use it versus get_audit_trail or get_evidence. This provides a specific purpose that differentiates it from alternatives.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('to recover recent workflows when you do not already know the task ID') and when to use alternatives ('use get_audit_trail or get_evidence once you have a specific task_id'). This provides clear, actionable guidance for tool selection.

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

• report_actionA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (appends to an audit log), its purpose (recording side effects), and what it returns (a small confirmation object). It could improve by mentioning potential rate limits or error conditions, but covers core behavior well.

  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 efficiently structured in two sentences with zero wasted words. The first sentence states the core purpose and usage context, while the second clarifies the return value and differentiation from report_status. Every sentence earns its place.

  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?

  Given the tool's moderate complexity (4 parameters, audit logging function) and 100% schema coverage but no output schema, the description provides good context about purpose, usage, and differentiation from siblings. It could slightly improve by mentioning what the 'small confirmation object' contains, but overall provides sufficient guidance for an agent to use it correctly.

  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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any additional parameter semantics beyond what's in the schema, but doesn't need to since the schema coverage is complete. This meets the baseline expectation for high schema coverage.

  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 clearly states the tool's purpose with specific verbs ('Append a tool execution outcome') and resource ('Attest audit log for the credential in use'), distinguishing it from siblings like report_status which handles lifecycle transitions. It explicitly defines the scope as recording side effects of meaningful business actions rather than authorizing them.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('after a meaningful business action such as sending email, updating billing, or calling an internal API') and when not to use it ('callers should use report_status for lifecycle transitions like started or completed'), clearly differentiating it from the sibling tool report_status.

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

• report_statusA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden of behavioral disclosure. It clearly states what the tool does (appends to audit log), what it doesn't do ('does not mint, verify, or revoke credentials'), and the return type ('Returns a confirmation object'). However, it doesn't mention authentication requirements, rate limits, or error conditions that would be helpful for a 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 perfectly concise with three focused sentences that each serve distinct purposes: stating the tool's function, providing usage guidelines, and clarifying behavioral boundaries. No wasted words, and the most important information appears first.

  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 mutation tool with no annotations and no output schema, the description does well by explaining the purpose, usage context, and behavioral boundaries. However, it could provide more detail about the confirmation object format or error handling. The 100% schema coverage helps compensate for some of these gaps.

  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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 reflects adequate parameter documentation through the schema alone.

  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 clearly states the specific action ('Append an agent lifecycle event') and target resource ('Attest audit log'), with explicit enumeration of event types ('started, completed, or failed'). It distinguishes from sibling 'report_action' by contrasting lifecycle events vs. concrete tool outcomes, providing clear differentiation.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('to mark step boundaries or overall task progress') and when to use an alternative ('use report_action for concrete tool outcomes instead'). This directly addresses the sibling relationship and gives clear context for tool selection.

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

• request_approvalA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it creates a pending approval request (implying a write operation), requires specific prerequisites ('valid parent token'), and returns a challenge object. However, it doesn't mention potential side effects like rate limits or error conditions, leaving some behavioral aspects uncovered.

  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 efficiently structured in two sentences: the first states the purpose and usage context, the second covers prerequisites and return value with references to sibling tools. Every sentence adds value without redundancy, making it appropriately sized and front-loaded.

  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 mutation tool with 5 required parameters, no annotations, and no output schema, the description provides good context: purpose, usage timing, prerequisites, and return object type. However, it doesn't detail the challenge object structure or error handling, which could be helpful given the complexity. The description is mostly complete but has minor gaps.

  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 description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal parameter semantics beyond the schema, only implying that 'parent_token' must be valid and 'requested_scope' relates to 'extra scope' approval. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

  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 clearly states the specific action ('Create a pending approval request') and resource ('for a high-risk delegation'), distinguishing it from siblings like grant_approval or deny_approval. It explicitly mentions the context ('after issuing or delegating a credential when a human must approve extra scope'), making the purpose unambiguous and distinct.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('after issuing or delegating a credential when a human must approve extra scope before work continues') and mentions alternatives for later steps ('can later be inspected with get_approval or resolved with grant_approval or deny_approval'). This clearly differentiates it from other tools in the workflow.

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

• revoke_credentialA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a state-changing operation (not read-only), has cascading effects, returns a confirmation object, and provides guidance on follow-up actions. It doesn't mention permissions, rate limits, or error conditions, but covers the essential mutation behavior adequately.

  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?

  Perfectly concise with three sentences that each earn their place: first explains the action and cascade, second provides usage context, third describes return behavior and follow-up guidance. No wasted words, front-loaded with the core functionality.

  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?

  Given no annotations and no output schema, the description does well to explain the mutation behavior, cascading effects, return type, and follow-up actions. It could mention what 'confirmation object' contains or error scenarios, but covers the essential context for a destructive operation with 2 parameters.

  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 description coverage is 100%, so the schema already documents both parameters (jti and revoked_by). The description doesn't add any additional parameter semantics beyond what's in the schema, but doesn't need to since schema coverage is complete. Baseline 3 is appropriate when schema does the heavy lifting.

  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 clearly states the specific action ('revoke one credential'), the scope ('cascade that revocation through all of its descendants in the same task tree'), and distinguishes it from siblings by mentioning alternatives like check_revocation and list_tasks. It goes beyond just restating the name to explain the cascading behavior.

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

  Usage Guidelines5/5

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

  Explicitly states when to use this tool ('when a workflow should be stopped or contained') and when not to use it ('not a dry run'), plus provides clear alternatives for follow-up actions ('later checks should use check_revocation or list_tasks rather than calling revoke_credential again'). This directly addresses sibling tool differentiation.

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

• verify_credentialA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by explaining the tool's behavior: it performs an 'offline-style' check (implying no network calls beyond JWKS fetch), requires org_id to fetch JWKS, and returns validity, decoded claims, and warning details. It doesn't mention rate limits, auth requirements, or error conditions, but provides substantial operational context.

  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 perfectly front-loaded with the core purpose in the first clause, followed by usage guidance and behavioral details. Every sentence earns its place by providing distinct value: purpose, when-to-use, alternative tool, requirements, and return values. No wasted words.

  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 2-parameter tool with no annotations and no output schema, the description provides excellent context about purpose, usage, and behavior. It explains what the tool returns (validity, decoded claims, warning details) which compensates for the missing output schema. The only minor gap is lack of error case documentation.

  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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal additional context about org_id ('needed to fetch JWKS'), but doesn't provide syntax, format, or validation details beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

  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 clearly states the specific action ('perform an offline-style validity check'), the resource ('one credential'), and the method ('using the org JWKS fetched from Attest'). It explicitly distinguishes from sibling 'check_revocation' by stating this is for validity checks while that is for revocation-only checks.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('to inspect a token before acting on it or when debugging why a credential was rejected') and when not to use it ('for revocation-only checks use check_revocation instead'). It names the specific alternative tool and clarifies the different use cases.

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