Server Quality Checklist

Tool Scores

• jisr_webhooks_listA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: 'Stored authentication material is never returned'—a meaningful security guarantee for agents. No contradiction with annotations.

  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?

  Two sentences with no filler. The first sentence identifies the purpose and the returned fields; the second adds a security-relevant behavior. Information is front-loaded and 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?

  For a read-only list tool with no required parameters, the description covers purpose, return fields, and a key security aspect. However, it doesn't explain cursor-based pagination or describe the response envelope, and there is no output schema to fill that gap. A modest addition would make it fully complete.

  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 for the two optional parameters. It doesn't mention cursor at all, leaving its pagination behavior unclear, and doesn't explain pageSize behavior beyond what the schema's min/max provide. The description thus fails to fill the schema gap.

  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 the specific verb 'Lists', identifies the resource as the organization's webhook subscriptions, and enumerates the exact returned fields (name, endpoint, HTTP method, status, subscribed events). This clearly distinguishes it from sibling list tools such as jisr_audit_events_list or jisr_departments_list by target resource.

  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 description provides no explicit guidance on when to use this tool versus alternatives—no 'use this when...' statement or exclusions. The purpose is clear enough that an agent can infer usage, but the description itself does not state the selection criteria.

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

• jisr_business_units_listA
  4.1/5.0
  Behavior3/5

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

  Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful return-content context (identifier and bilingual names) but does not describe pagination behavior or any operational traits beyond what annotations and schema already cover.

  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?

  Two sentences with no filler: the first states the primary function and return fields, the second states the practical purpose. All content earns its place and the key action verb is front-loaded.

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

  Completeness5/5

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

  For a simple, read-only list tool with clear annotations and fully documented pagination parameters, the description is complete. It tells the agent what the tool returns (identifier and bilingual names), why to use it (identifier resolution), and the structured schema already covers pagination.

  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 cursor and pageSize are already fully documented in the schema. The description adds no parameter-level information, which is acceptable because the schema carries that burden.

  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?

  States a specific verb ('Lists'), a specific resource ('business units'), and the exact content returned (identifier plus English and Arabic names). The added use-case sentence ('resolve names to stable identifiers before filtering other tools') gives it a distinct identity among the many sibling list tools, so an agent can tell it apart.

  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 description gives a clear, explicit purpose: use business-unit identifiers to resolve names before filtering other tools. It does not explicitly name alternatives or state when not to use this tool, but it provides enough contextual guidance to select it for identifier resolution.

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

• jisr_nationalities_listA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered by structured metadata. The description adds useful context about the returned fields and scope, but it doesn't disclose additional behavioral traits such as pagination behavior beyond what the schema already shows.

  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?

  Both sentences earn their place: the first states what the tool returns, and the second explains why an agent would use it. There is no filler or repetition of information already present in the schema or annotations.

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

  Completeness5/5

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

  For a simple, no-required-parameter list tool with annotations covering read-only behavior and schema covering pagination, the description is complete. It tells the agent what is returned, the scope, and the intended use case without requiring an output schema.

  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%, with both cursor and pageSize already documented in the input schema. The description adds no additional parameter-level meaning, which is fine because the schema already carries the semantic burden.

  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 lists the organization's nationalities and specifies the key output fields: identifier, English name, and Arabic name. This clearly separates it from sibling list tools for departments, locations, employment types, and so on.

  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?

  It provides clear usage context: use these values to resolve names to stable identifiers before filtering other tools. It doesn't explicitly mention when not to use it or name alternatives, but the purpose is specific enough that an agent can recognize it as a reference lookup tool.

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

• jisr_connection_status_getA
  4.2/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by explicitly stating that no credentials or organization identifiers are returned, which manages expectations about sensitive data exposure. It also discloses the specific pieces of status information included.

  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, tightly packed sentence that front-loads the primary purpose and then adds the key exclusion. No wasted words; every clause 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?

  Without an output schema, the description helpfully enumerates the main reported fields (reachability, last authentication time, last error) and the privacy boundary. For a simple status check this is sufficient, though it could theoretically mention whether the call requires any prerequisites or how to interpret a missing auth time.

  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?

  The tool has zero parameters, so there is nothing for the description to add about parameter usage. The schema is vacuously complete at 100% coverage, and the description avoids inventing unnecessary parameter details, giving the baseline 4.

  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 ('Reports') with a clear resource (whether the server can reach Jisr, last authentication time, and error). It explicitly differentiates itself by stating what it does not return, which distinguishes it from sibling tools that list data or capabilities.

  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 description implies this tool is for checking connection/authentication status, but it does not explicitly state when to prefer it over sibling tools or mention any exclusions. Since no alternatives are named, the usage context is only implied.

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

• jisr_data_catalog_getA
  4.2/5.0
  Behavior4/5

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

  Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds valuable behavioral context beyond them: the tool returns no records, explains pagination semantics, and indicates data freshness. This helps the agent set expectations for the response without contradicting any annotation.

  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?

  Two tight sentences convey scope, content, pagination behavior, freshness, and a key exclusion ('Returns no records') with no filler. The most important 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 low-complexity read-only catalog tool with one optional parameter and rich annotations, the description covers the essential context: what the catalog contains, pagination, freshness, and the absence of records. It does not enumerate the actual domains, but that is inherently the tool's output rather than a precondition.

  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 100% and the schema already describes the only parameter, 'domain', as 'Limit the catalog to one domain.' The description adds context about domains but does not add new parameter-level meaning beyond what the schema provides. Baseline 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 names a specific verb ('Describes') and resource ('available Jisr domains'), and enumerates the concrete contents: tools per domain, classified field groups, pagination, and data freshness. It also explicitly distinguishes itself from data-returning siblings by saying 'Returns no records.'

  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 description gives clear context for when to call this tool: when an agent needs to understand which Jisr domains exist, which tools serve them, and how pagination/freshness behave. It does not explicitly name alternatives or state when not to use it, but the contrast with record-returning sibling list tools is implied by 'Returns no records.'

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

• jisr_capabilities_getA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover safety (readOnly, idempotent, non-destructive), and the descripion adds meaningful operational context: it reports permission checks against API key, role, and operator enablement, plus remediation hints. This goes beyond the structured hints and gives an agent useful expectations about the tool's diagnostic nature.

  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 two sentences with no filler. The primary action is front-loaded, and the four-fact breakdown is clearly structured, making the tool's behavior easy to parse quickly.

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

  Completeness5/5

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

  Given the tool has no parameters, no output schema, and simple read-only behavior, the descripion fully explains what the tool returns, what dimensions it covers, and that it offers rationale and ownership for unavailability. Nothing essential is missing for an agent to decide when and how to invoke it.

  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?

  The tool has zero parameters, so there is no parameter semantics to document. The schema coverage is trivially 100%, and the description appropriately focuses on output content rather than inputs.

  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 ('Lists'), names the resource ('every documented Jisr operation'), and details the scope with four concrete fact types. This clearly distinguishes it from the sibling data-list tools, which target specific entities rather than the operation catalog itself.

  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 description implies its use for discovering which Jisr operations are available and diagnosing why some are not, by stating the four facts and that it explains unavailability. However, it does not explicitly say when to use it instead of a sibling tool or state exclusions, so guidance remains 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.

• jisr_departments_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond the annotations by disclosing that identifiers are stable and that the tool is meant for resolving names to identifiers.

  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?

  Two focused sentences: the first states what the tool does and returns, the second states its intended usage. Every word earns its place, with no filler or repetition.

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

  Completeness5/5

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

  For a simple read-only list tool with fully documented optional parameters, the description is complete: it specifies the resource, output fields, and the operational context. The absence of an output schema is compensated by describing what each listed item contains.

  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%, with both cursor and pageSize already documented. The description adds no parameter-specific details beyond the schema, so the baseline 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 states a specific verb ('Lists'), a concrete resource ('the organization's departments'), and the exact output contents ('identifier and both English and Arabic names'). It is clearly distinguishable from sibling list tools by naming 'departments' as the resource.

  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 description gives explicit context for when to use this tool: 'Use these to resolve names to stable identifiers before filtering other tools.' It does not discuss exclusions or alternatives, but the intended use case is clear.

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

• jisr_employment_types_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by explaining the returned data shape (identifier plus bilingual names) and the intended role of these identifiers in downstream filtering.

  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 two concise, front-loaded sentences. The first states exactly what the tool does, and the second explains why an agent would use it. No filler or redundant content.

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

  Completeness5/5

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

  For a simple, read-only list tool with optional pagination and no required parameters, the description fully covers the tool's purpose, result contents, and usage intent. Annotations and schema handle safety and parameter details, so nothing essential is missing.

  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 both optional parameters (cursor and pageSize) are already fully documented. The description adds no parameter-specific details beyond what the schema provides, which fits 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 uses a specific verb and resource: 'Lists the organization's employment types'. It also specifies what each item contains (identifier, English and Arabic names), making the tool's purpose unambiguous and distinguishing it from sibling list tools for other entities.

  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 description gives clear context for use: resolving names to stable identifiers before filtering other tools. It does not explicitly list exclusions or alternative tools, but for a simple list endpoint the stated purpose is sufficient guidance.

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

• jisr_locations_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is not the description's burden. The description adds useful context beyond annotations by noting that identifiers are stable and that both English and Arabic names are returned, which helps an agent reuse the output correctly.

  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?

  Two short sentences with no filler: the first states the operation and output shape, the second states the intended use. The most important information is front-loaded.

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

  Completeness5/5

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

  For a low-complexity, read-only list tool with no output schema, the description explains the returned record shape and the workflow role. Combined with the schema's pagination fields and the annotations, an agent has enough to invoke 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?

  Both parameters (cursor and pageSize) are fully described in the schema, so schema coverage is 100%. The description provides no additional parameter-level meaning, so the baseline 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 names a specific verb ('Lists') and resource ('the organization's locations'), and further specifies the output contents: identifier plus English and Arabic names. This clearly distinguishes it from sibling list tools such as jisr_departments_list or jisr_business_units_list.

  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?

  It gives an explicit use case: resolve names to stable identifiers before filtering other tools. It does not name alternatives or list when not to use it, but the context is clear enough for an agent to select this tool when a location identifier is needed.

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

• jisr_outsourcing_companies_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context beyond that: each entry contains an identifier and both English and Arabic names, and the output is intended for resolving names to stable IDs. No contradiction with annotations.

  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?

  Two sentences, each earning its place: the first states action and output, the second states the purpose. No wasted words or redundant restatement of schema or annotations.

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

  Completeness5/5

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

  For a simple read-only list with no required parameters and no output schema, the description is complete. It covers what the tool returns, why an agent would call it, and pagination is already handled by the schema. Nothing essential is missing.

  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%, and both cursor and pageSize already have clear descriptions in the input schema. The description adds no parameter-level meaning, so the baseline of 3 applies.

  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?

  States a specific verb and resource: 'Lists the organization's outsourcing companies.' It also enumerates the key return fields (identifier, English and Arabic names), making the tool's purpose concrete. The resource is unique among the sibling list tools, so an agent can distinguish it from departments, locations, or nationalities lists.

  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?

  Provides clear usage context: 'Use these to resolve names to stable identifiers before filtering other tools.' This tells the agent when this tool is the right first step, though it does not explicitly name alternatives or provide 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.

• jisr_audit_events_listA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare this as a safe, read-only, idempotent, non-destructive operation. The description adds a useful behavioral detail beyond the annotations: filters are passed as ordinary named inputs and the server converts them into Jisr's bracketed query syntax, preventing an agent from manually constructing that syntax. It does not discuss pagination or output shape, but the annotations lower the bar for safety disclosure.

  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?

  Two sentences with no filler. The core action is front-loaded and the important encoding behavior is stated in the second sentence. Every sentence contributes meaningful, non-redundant information.

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

  Completeness5/5

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

  For a read-only list endpoint with all optional parameters and safety already disclosed by annotations, the description is sufficient for an agent to call it correctly. It explains filtering, names the filter dimensions, and warns about the bracket syntax conversion. Pagination and return fields are not described, but no output schema exists and the annotation profile makes these gaps minor.

  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?

  Schema description coverage is low at 29%, so the description must compensate. It meaningfully identifies the filterable parameters (moduleName, eventName, eventType, fromDate/toDate) and clarifies the server-side encoding behavior. cursor and pageSize are not described, but they are conventional and the overall filter semantics are substantially clarified beyond what the schema provides.

  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 and resource: 'Lists Jisr audit events'. It further distinguishes the scope by naming the filter dimensions (module, event name, event type, date range), which is more specific than the title alone and clearly separates it from the sibling list tools that target different resources.

  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 description implicitly establishes when to use this tool: whenever Jisr audit events need to be listed and filtered. It provides clear context about the supported filters but does not explicitly mention when not to use it or name alternatives, though no sibling tool competes for audit events.

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