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

With no annotations, the description carries full disclosure burden. It successfully explains the critical side-effect constraint (no read consumption), documents return value structure (status, reads used/remaining, expiry), and defines domain-specific state ('sealed'). Missing only generic items like error conditions or auth requirements.

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

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

Four sentences with zero waste: (1) core purpose + key constraint, (2-3) specific use cases, (4) domain concept definition. Information is front-loaded with the critical 'no read consumption' differentiator. Every sentence earns its place.

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

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

Given the single parameter, lack of annotations, and absence of output schema, the description is complete. It compensates for the missing output schema by detailing return fields (status, reads, expiry) and explains the 'sealed' domain logic necessary for correct interpretation of results.

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

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

Schema description coverage is 100%, documenting the 'key' parameter formats ('sirr:KEYNAME', 'KEYNAME#id', etc.). The description implies the key identifies the secret to check but does not add semantic meaning beyond the comprehensive schema, warranting the baseline score for high-coverage schemas.

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

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

The description uses specific verbs ('Check', 'inspect') and clearly identifies the resource (secret metadata). It effectively distinguishes itself from sibling 'get_secret' by emphasizing 'WITHOUT consuming a read' and positioning itself as the pre-fetch verification step.

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

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

Provides explicit 'when-to-use' guidance: 'before fetching it' (implying get_secret) and for inspecting 'read counts and expiry'. Clear context for why to choose this over the fetch alternative, though it could explicitly name 'get_secret' for a perfect 5.

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

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

Strong behavioral signals without annotations: 'Immediately' indicates synchronous execution, 'burn' implies irreversible destruction, and 'regardless of TTL' discloses force-delete behavior. However, missing critical safety context for a destructive tool: no mention of permanent data loss, authorization requirements, or error behavior if key doesn't exist.

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

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

Single dense sentence with zero waste. Front-loaded action ('Immediately delete'), parenthetical clarification ('burn'), and scoping clause ('regardless of TTL') each serve distinct purposes without redundancy.

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

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

Appropriately complete for a single-parameter destructive operation. Captures the unique behavioral quirk (TTL bypass) that defines this tool. Minor gap: lacks explicit irreversibility warning ('this cannot be undone') which would be ideal for a vault deletion tool, though 'burn' implies this strongly.

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

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

Schema coverage is 100% with clear parameter description ('Key name to delete'), establishing baseline 3. The description mentions 'secret' and implies the key parameter, but adds no supplementary semantics about key format, naming constraints, or examples beyond what the schema already provides.

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

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

Excellent specificity with 'delete (burn)' verb phrase plus resource 'secret from the Sirr vault.' The clause 'regardless of TTL or read count' effectively distinguishes from siblings like prune_secrets (likely cleanup) or automatic expiration, clarifying this forces immediate deletion vs. natural lifecycle expiration.

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

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

Implies usage context via 'regardless of TTL or read count' (use when you need to bypass normal expiration), but lacks explicit when-to-use guidance or warnings about alternatives (e.g., 'Use only when immediate revocation is required; otherwise secrets expire automatically').

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

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

With no annotations provided, the description carries full behavioral burden and excels: it discloses the read-counter side effect, automatic deletion for max_reads=1, null-return conditions (missing/expired/burned), and critical security requirements for ephemeral handling of returned values.

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

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

Every sentence earns its place: purpose statement, side-effect warning, return-value documentation, input format clarification, and security imperative. Well front-loaded and appropriately dense for a security-critical operation.

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

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

Despite lacking an output schema and annotations, the description comprehensively covers return behavior (null conditions), destructive side effects, and security handling requirements necessary for safe invocation of a secret-retrieval tool with auto-destruct capabilities.

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

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

Schema coverage is 100%, so the schema already fully documents the 'key' parameter including accepted formats. The description repeats this information ('Accepts bare key names...') but does not add new semantic constraints, validation rules, or examples beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Retrieve a secret from the Sirr vault by key name') and distinguishes itself from siblings like check_secret and delete_secret by explicitly describing the read-counter incrementation and conditional deletion behavior unique to this retrieval operation.

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

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

Provides clear context on security constraints ('Do not store, log, memorize...') and input format options. However, it does not explicitly name alternative tools (e.g., 'use check_secret to verify existence without consuming reads') despite implying the distinction through the read-counter description.

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

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 implies a safe, read-only operation ('Check'), but does not disclose what constitutes 'healthy', whether authentication is required, or what the response format looks like.

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

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

Single sentence, nine words, zero redundancy. The description is immediately front-loaded with the essential action and target.

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

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

Given the low complexity (no parameters, simple boolean/health status concept) and absence of an output schema, the description is sufficient. It could be improved by indicating the return value format (e.g., boolean vs status object).

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

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

With zero parameters, the baseline score applies. The description correctly implies no configuration is needed for this health probe, matching the empty input schema.

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

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

The description uses a specific verb ('Check') with a clear resource ('Sirr server') and scope ('reachable and healthy'). It clearly distinguishes this diagnostic tool from the numerous secret-management and org-management siblings (get_secret, sirr_org_create, etc.).

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

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

While no explicit 'when to use' or alternative tools are mentioned, usage is implied by the unique diagnostic nature of the tool among its operational siblings. However, it lacks guidance on when to prefer this over simply attempting an operation.

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

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

With no annotations provided, the description carries the full disclosure burden. It explicitly states the security-critical behavior that 'values are never included' and details the returned metadata fields (key name, expiry time, read count), compensating for the missing output schema. Lacks pagination or rate limit disclosure.

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

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

Three tightly constructed sentences: purpose (sentence 1), behavioral safety (sentence 2), and output structure (sentence 3). Front-loaded with the core action, zero redundancy, every clause adds value beyond the structured fields.

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

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

For a zero-parameter list operation, the description adequately compensates for the missing output schema by enumerating the returned metadata fields. Could be improved by noting pagination behavior or maximum result limits when listing 'all' secrets.

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

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

Input schema has zero parameters, establishing baseline 4. The description correctly omits parameter discussion since none exist, and the 'all active secrets' phrasing implies no filtering parameters are required.

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

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

States specific verb (List) + resource (secrets) + scope (active secrets in Sirr vault). The 'metadata only' and 'values are never included' clauses clearly distinguish from sibling get_secret, establishing this as an enumeration tool rather than a retrieval tool.

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

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

Provides clear context about what the tool returns (metadata vs values), implicitly guiding the agent to use get_secret for actual values. However, it does not explicitly name alternatives or state 'when-not' conditions (e.g., 'do not use for retrieving secret values, use get_secret instead').

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

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

With no annotations, description carries full burden. It discloses PATCH semantics ('All fields are optional — only provided fields are changed'), but omits error behavior (what if key missing?), return values, or side effects.

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

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

Two sentences with zero waste. Front-loaded with main action ('Update an existing secret...'), followed immediately by critical behavioral constraint. Every word earns its place.

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

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

Adequate for a 4-parameter mutation tool but gaps remain. Given no output schema and no annotations, description should ideally specify return values and error cases (e.g., key not found behavior).

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining parameter interaction: 'All fields are optional' and 'only provided fields are changed' clarifies partial update behavior beyond individual parameter descriptions.

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

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

Description states 'Update an existing secret's value, TTL, or max read count' — specific verb (Update) + resource (secret) + specific fields. Clearly distinguishes from siblings like push_secret (create), get_secret (read), and delete_secret.

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

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

Implies usage by stating 'existing secret' and explains partial update semantics ('only provided fields are changed'), but lacks explicit guidance on when to use vs push_secret or prerequisites like 'secret must exist'.

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

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

With no annotations provided, the description carries the full burden. It explicitly discloses the destructive nature ('secrets that were deleted') and return value ('count'), indicating this is an immediate, irreversible mutation. Could be improved by mentioning permission requirements or if the deletion is permanent vs. soft-delete.

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

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

Two sentences total with zero waste. First sentence establishes the action and target; second sentence discloses the return value. Information is front-loaded and every word earns its place.

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

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

For a zero-parameter destructive operation, the description is appropriately complete. It compensates for the lack of output schema by stating the return value ('count of secrets that were deleted'). Only minor gap is the lack of safety warnings given the destructive nature.

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

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

Input schema contains zero parameters. Per rubric guidelines, this establishes a baseline score of 4, as there are no parameter semantics to clarify beyond the schema.

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

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

Description uses specific verb 'Trigger an immediate sweep' and clearly identifies the resource as 'all expired secrets.' The scope ('all' + 'expired') effectively distinguishes this bulk cleanup operation from sibling tools like delete_secret (likely single-item) and list_secrets (non-destructive).

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

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

Provides clear context that this targets 'expired' secrets specifically and operates as a bulk 'sweep,' implying usage for cleanup tasks rather than selective deletion. However, it does not explicitly name alternatives (e.g., 'use delete_secret to remove specific non-expired secrets') or state prerequisites.

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

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

Excellent disclosure of behavioral traits beyond the missing annotations: explains the 'burn after reading' deletion pattern, contrasts deletion versus sealing behavior (including the specific HTTP 410 response for sealed secrets), and clarifies default behaviors ('By default, the secret is deleted when burned').

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

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

Four tightly constructed sentences with zero redundancy. Front-loaded with the core purpose, followed by optional parameters, specific usage patterns, and behavioral side effects. Every sentence earns its place by adding actionable guidance.

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

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

Comprehensive for a creation tool despite no output schema: it covers the secret lifecycle (TTL, read limits, deletion vs sealing) and side effects. Minor gap: does not mention what the operation returns on success (e.g., confirmation or the key ID), though this is often standard for push operations.

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

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

While the schema has 100% description coverage (baseline 3), the description adds significant use-case context that the schema lacks: it explains the business logic for max_reads=1 ('one-time credentials that burn after first access'), ttl_seconds ('time-expiring secrets'), and the semantic difference between delete=true (deletion) versus delete=false (sealing).

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

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

The description opens with the specific action ('Store') and resource ('secret in the Sirr vault'), clearly distinguishing it from sibling tools like get_secret, delete_secret, or patch_secret. The verb 'Store' combined with the tool name 'push_secret' unambiguously indicates a write operation for secret creation.

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

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

Provides explicit guidance on when to use specific parameter combinations ('Use max_reads=1 for one-time credentials', 'Use ttl_seconds for time-expiring secrets'). However, it does not explicitly differentiate when to use push_secret versus patch_secret for updates, or mention prerequisites like authentication/authorization requirements.

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

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

No annotations provided, yet description fully compensates by disclosing expiration policy (24h or single-use), authentication requirements (none), hosting domain (sirrlock.com), return type (URL), and destructive nature (burn-after-read). No contradictions.

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

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

Five well-structured sentences: purpose, auth context, expiration behavior, return value, and security warning. Every sentence earns its place. Front-loaded with core functionality. No redundancy.

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

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

For a single-parameter tool, description is complete. Compensates for missing output schema by explicitly stating 'Returns a URL to send to the recipient.' Security warnings and expiration details provide necessary context for safe operation.

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

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

Schema has 100% coverage with clear description of 'value' parameter. Description reinforces sensitivity context but adds minimal semantic detail beyond the schema. With high schema coverage, baseline 3 is appropriate.

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

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

States specific verb (share), resource (sensitive value), and mechanism (secure burn-after-read link hosted on sirrlock.com). Clearly distinguishes from siblings like push_secret, get_secret, or list_secrets by emphasizing the external link-sharing mechanism.

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

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

Provides explicit security guidance ('Do not store or repeat the secret value') and prerequisites ('No account or token required'). Lacks explicit comparison to sibling alternatives like push_secret, but the burn-after-read mechanism provides implicit context for when to use this tool.

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

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

With no annotations, description carries full burden. 'Query' and 'Returns' establish read-only safety, and lists event types (creates, reads, deletes), but omits rate limits, data retention windows, pagination behavior, or auth requirements.

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

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

Two well-structured sentences with zero waste. Front-loaded with core action (Query the Sirr audit log), followed by return value and use cases. Every sentence earns its place.

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

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

Appropriate for a 4-parameter query tool with full schema coverage. Mentions return value ('Returns recent events') despite lack of output schema. Could note that all parameters are optional, but sufficient for selection and invocation.

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

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

Schema has 100% coverage (baseline 3). Description adds value by providing concrete action examples ('secret creates, reads, deletes') that help interpret the 'action' parameter and contextualizes temporal filters as 'recent events'.

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

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

States specific verb 'Query' and resource 'Sirr audit log', clearly distinguishing from sibling management tools (create_key, delete_secret, etc.) by focusing on logging/auditing rather than resource manipulation.

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

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

Provides implied usage via 'Useful for security monitoring and debugging access patterns' but lacks explicit when-not-to-use guidance or alternatives (e.g., doesn't clarify when to use vs get_secret for history).

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

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

No annotations provided, so description carries full burden. Discloses crucial behavioral traits: the raw key is returned only once (one-time exposure), must be saved immediately (client-side storage required), and operates on /me/keys endpoint (current principal scope). Does not mention auth requirements or rate limits.

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

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

Two sentences with zero waste. First sentence front-loads the action and target. Second sentence delivers the critical warning about key handling. Every word earns its place; no redundancy with schema or title.

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

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

For an API key creation tool with no output schema, the description captures the essential completeness factor: the one-time nature of the returned secret. Missing explicit return value description (format of the key), but the warning about immediate saving compensates adequately for the missing output schema.

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

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

Schema description coverage is 100%, with all three parameters (name, valid_for_seconds, valid_before) fully documented in the schema. The description implies these configure the key but doesn't add syntax details, format examples, or constraints beyond what's in the schema. Baseline 3 appropriate given high schema coverage.

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

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

Specific verb 'Create' + resource 'API key' + scope 'for the current principal via /me/keys' clearly distinguishes from siblings like sirr_key_list (list) and sirr_delete_key (delete). The endpoint reference adds precise scoping.

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

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

Provides critical operational guidance: 'The raw key is returned once — save it immediately.' This warns about the irretrievable nature of the secret material. Lacks explicit comparison to alternatives (e.g., when to use sirr_key_list instead), but the handling instruction is essential usage guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the destructive nature through the word 'Revoke,' but fails to mention that this action is permanent, whether it triggers immediate invalidation of active sessions, or what error occurs if the key doesn't exist.

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

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

The description is a single, efficient sentence with zero redundancy. The critical constraint ('belonging to the current principal') is included in the main statement rather than buried in secondary text.

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

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

For a single-parameter deletion tool with 100% schema coverage and no output schema, the description is nearly sufficient. It would benefit from an irreversibility warning, but the core functionality, ownership constraints, and parameter requirements are all addressed.

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

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

Schema description coverage is 100%, with the keyId parameter already documented as 'API key ID to delete.' The description does not add parameter-specific semantics (such as where to obtain the ID or expected format), so it meets the baseline for high-coverage schemas.

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

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

The description uses a specific verb ('Revoke'), identifies the exact resource ('API key'), and clearly constrains the scope ('belonging to the current principal'). This distinguishes it from siblings like delete_secret (which handles secrets) and sirr_create_key (which creates rather than removes keys).

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

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

The phrase 'belonging to the current principal' provides an important constraint implying the tool cannot delete other users' keys, but there is no explicit guidance on when to use this versus sirr_key_list (to obtain the ID) or warnings about irreversibility.

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

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

No annotations provided, so description carries full burden. Critically discloses that 'Key values are never returned,' a key security behavior. Implies read-only operation via 'List,' though could explicitly state it is non-destructive.

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

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

Two sentences, zero waste. First sentence states purpose; second sentence provides critical behavioral constraint. Efficiently front-loaded with no filler.

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

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

Appropriate for a zero-parameter list operation. Covers the essential security constraint (key values omitted). Without output schema, could mention that metadata (IDs, creation dates) is returned, but sufficient for the tool's complexity.

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

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

Zero parameters per input schema (empty properties object). Baseline score applies as there are no parameters requiring semantic explanation beyond the schema.

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

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

States specific verb (List), resource (API keys), and scope (for the current principal). Clearly distinguishes from siblings sirr_create_key, sirr_delete_key, and list_secrets by specifying operation type and resource.

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

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

Provides implicit guidance through 'Key values are never returned,' indicating when NOT to use it (when key values are needed). However, lacks explicit when-to-use guidance or mention of alternatives like sirr_create_key for generating new keys.

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

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

No annotations provided, so the description carries full disclosure burden. It successfully indicates the return payload ('account details and current plan information'), but lacks details on rate limits, caching behavior, or explicit safety guarantees that would be helpful without readOnlyHint annotations.

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

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

Two sentences with zero waste: first states the operation and target, second states the return value. Information is front-loaded and appropriately sized for the tool's simplicity.

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

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

Given the lack of output schema, the description compensates by specifying the return value contains 'account details and current plan information'. For a zero-parameter read operation, this provides sufficient context, though specific field names would strengthen it further.

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

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

Zero parameters present, which establishes a baseline of 4 per rubric. No parameter description is needed or provided, which is appropriate for this simple getter endpoint.

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

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

Specific verb 'Get' with clear resource 'authenticated user/org profile'. The phrase 'current authenticated' effectively distinguishes this from sibling tools like sirr_org_list (which lists all orgs) and sirr_principal_list (which lists principals), clarifying this retrieves the caller's own profile.

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

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

Provides no explicit guidance on when to use versus alternatives. While the description implies this is for retrieving the current user's context, it does not state when to prefer this over sirr_org_list or whether it should be called before other operations.

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

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

No annotations provided, so description carries full burden. Adds critical auth requirements missing from structured data. However, fails to disclose return value structure (no output schema exists), idempotency behavior, or error cases for this mutation operation.

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

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

Two sentences with zero waste: first states purpose, second states auth requirements. Front-loaded and appropriately sized for the tool's complexity.

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

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

Sufficient for basic invocation given complete input schema documentation and auth context. However, as a creation tool with no output schema, the description should specify what is returned (e.g., organization ID/object) to be fully complete.

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

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

Schema description coverage is 100%, so the schema fully documents both 'name' and 'metadata' parameters. Description adds no parameter-specific guidance beyond schema, warranting baseline score of 3 per rubric for high-coverage schemas.

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

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

Specific verb ('Create') + resource ('organization') clearly stated. Distinct from sibling tools like sirr_org_delete and sirr_org_list through the explicit action verb.

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

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

Provides clear prerequisite context ('Requires master key or sirr_admin permission') indicating when the tool can be invoked. Lacks explicit comparison to alternatives (e.g., 'use this instead of sirr_org_list'), but the permission constraint provides concrete usage context.

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

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

With no annotations provided, the description carries the full disclosure burden. It effectively communicates the destructive nature ('Delete'), authorization requirements ('master key'), and critical state constraints ('no principals'). It lacks details on error behavior or return values, preventing a perfect score.

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

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

Three sentences with zero waste: action definition, business constraint, and auth requirement. Information is front-loaded with the verb, and every clause is essential for safe invocation.

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

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

For a single-parameter destructive operation with no output schema, the description adequately covers the critical safety prerequisites (master key, empty org) needed to prevent accidental misuse. It omits return value documentation, which is the primary gap.

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

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

Schema description coverage is 100%, establishing a baseline of 3. The description mentions 'by ID' which aligns with the org_id parameter, but adds no additional semantic detail (e.g., ID format, examples) beyond what the schema already provides.

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

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

The description opens with the specific verb 'Delete' and resource 'organization', clearly distinguishing this from sibling tools like sirr_org_create and sirr_org_list. The 'by ID' phrase precisely scopes the operation.

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

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

The description provides explicit constraints ('Org must have no principals') and prerequisites ('Requires master key'), which function as when-not-to-use guidance. However, it does not explicitly name alternative tools like sirr_principal_delete that should be used first to satisfy the constraint.

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

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 successfully communicates the authentication requirement (master key), but omits other behavioral traits like pagination behavior, rate limits, or error conditions that would be expected for a 'list all' operation.

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

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

The description consists of two efficient sentences with zero waste: the first establishes the function, the second states the critical auth requirement. It is appropriately front-loaded and sized for the tool's simplicity.

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

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

Given the tool has zero parameters, no output schema, and performs a standard CRUD list operation, the description is sufficiently complete. The master key requirement is crucial context for a 'list all' operation that would otherwise appear unprotected.

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

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

The input schema contains zero parameters, which establishes a baseline of 4. The description does not need to compensate for missing parameter documentation, and the auth requirement is appropriately placed in the description rather than the schema.

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

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

The description clearly states the action ('List') and resource ('organizations'), distinguishing it from sibling tools that manage secrets, keys, principals, or other entities. However, it lacks explicit scoping details (e.g., whether this lists all orgs globally or just accessible ones) that would make it a 5.

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

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

The description provides a clear prerequisite ('Requires master key') indicating when the tool can be used, but fails to mention when not to use it or suggest alternatives (e.g., when to use sirr_org_create instead).

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

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 only indicates this is a mutative 'Create' operation but fails to disclose idempotency, return values (created principal ID?), error cases, or side effects. Insufficient for a write operation.

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

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

Extremely concise at 9 words with zero redundancy. However, given the complexity (4 parameters, nested objects, mutative operation, IAM context), this brevity comes at the cost of missing critical operational details.

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

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

For a 4-parameter mutative IAM tool with dependencies on existing orgs/roles, no output schema, and zero annotations, a 9-word description is inadequate. Missing: return structure, validation behavior, and relationship to sirr_role_create prerequisites.

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

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

Schema description coverage is 100%, documenting org_id, name constraints, role requirements, and optional metadata. The description adds no parameter-specific guidance, but the comprehensive schema makes this acceptable at baseline level.

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

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

The description states the specific verb ('Create') and resource ('principal (user/service)') with scope ('in an organization'), distinguishing it from sibling creation tools like sirr_org_create or sirr_role_create. However, it misses the opportunity to clarify how principals relate to roles and organizations.

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

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

No guidance provided on when to use this versus alternatives, prerequisites (e.g., requiring an existing organization and role), or error conditions. The description is purely declarative with no operational context.

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

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

With no annotations provided, the description carries the full burden. It successfully discloses the validation constraint (no active keys required), revealing a key behavioral trait. However, it lacks details on error behavior, reversibility, or side effects that would be expected for a destructive operation.

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

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

Two sentences with zero waste. The first states the action; the second states the critical constraint. Perfectly front-loaded and efficient.

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

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

Appropriately complete for a simple two-parameter deletion tool. The constraint about active keys provides essential context. Lacks output description, but for a delete operation with no output schema, this is acceptable.

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

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

Schema description coverage is 100% (both org_id and principal_id have descriptions). The description does not add parameter-specific semantics beyond the schema, meeting the baseline expectation for well-documented schemas.

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

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

Description provides specific verb ('Delete'), resource ('principal'), and scope ('from an organization'). It clearly distinguishes from siblings like sirr_org_delete and sirr_role_delete by focusing on principals.

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

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

States the critical prerequisite 'Principal must have no active keys,' which implies when the operation will fail. However, it does not explicitly reference sirr_delete_key or sirr_key_list as the prerequisite workflow steps.

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

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 but fails to mention pagination behavior, authorization requirements, error conditions (e.g., invalid org_id), or whether the operation is read-only. The phrase 'List all' implies a complete set but doesn't clarify result limits.

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

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

The description is a single, efficient sentence with no wasted words. It is appropriately front-loaded with the action and resource. While extremely terse, it avoids the verbosity that would lower this score.

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

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

Given the absence of an output schema, the description should ideally indicate what constitutes a 'principal' or the expected return structure. While adequate for identifying the tool's general function, it leaves critical gaps regarding the response format and entity definitions needed for an agent to process results effectively.

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

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

The input schema has 100% description coverage for its single parameter (org_id). The description adds no additional semantic context about the organization ID format or how to obtain it, meeting the baseline expectation when the schema is self-documenting.

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

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

The description uses a specific verb ('List') and resource ('principals') with scope ('in an organization'), clearly distinguishing it from sibling tools like sirr_principal_create or sirr_org_list. However, it lacks definition of what constitutes a 'principal' in this system (user, service account, etc.).

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

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

The description provides no guidance on when to use this tool versus alternatives like sirr_me (which gets current user info) or sirr_org_list. It does not mention prerequisites, permissions, or filtering capabilities.

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

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

With no annotations provided, the description carries the full burden. It successfully explains the permission encoding scheme (letter-to-action mapping), but fails to disclose side effects, idempotency behavior (e.g., duplicate role names), or return values.

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

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

The description consists of exactly two high-value sentences with no redundancy: the first establishes purpose, the second explains the permission syntax. Information is front-loaded and appropriately dense.

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

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

Given the absence of an output schema, the description adequately covers inputs via the permission mapping, but remains incomplete regarding return values (e.g., whether it returns the role ID) and error conditions for a creation operation.

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

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

While the schema has 100% coverage (baseline 3), the description adds crucial semantic value by providing the complete mapping of permission letters (C=create, P=patch, M=manage, etc.) beyond the schema's single example ('CRL').

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

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

The description clearly states the specific action ('Create a custom role') and resource ('in an organization'), distinguishing it from sibling tools like sirr_role_delete and sirr_role_list through the explicit 'Create' verb.

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

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

The description implies when to use the tool (to create custom roles with specific permissions), but lacks explicit guidance on when not to use it, prerequisites, or references to alternative tools like sirr_role_list for viewing existing roles.

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

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 adds valuable constraint context (built-in and in-use restrictions) but lacks details on what happens when constraints are violated (error type), whether deletion is permanent, or required permissions.

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

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

Two sentences total with zero waste. The first sentence front-loads the primary action, and the second sentence provides critical guardrails. Every word earns its place.

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

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

For a simple 2-parameter deletion tool with no output schema and complete parameter documentation, the description is adequately complete. It covers the essential business logic constraints (custom-only, not-in-use), though it could mention the irreversible nature of the deletion given the lack of safety annotations.

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

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

The input schema has 100% description coverage for both parameters ('Organization ID' and 'Role name to delete'). The description does not add syntax details, validation rules, or semantics beyond what the schema already provides, meeting the baseline for high-coverage schemas.

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

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

The description uses a specific verb ('Delete') with a clear resource ('custom role') and scope ('from an organization'). It effectively distinguishes from siblings by specifying 'custom role' (implying built-in roles are handled differently) and contrasts with sirr_role_create and sirr_role_list.

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

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

The description provides clear negative constraints ('Cannot delete built-in roles or roles in use'), indicating when not to use the tool. However, it does not explicitly name alternative tools (e.g., suggesting sirr_role_list to check usage first) or provide explicit 'when to use' guidance beyond the basic purpose.

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

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

No annotations are provided, so the description carries the full burden. While 'List' implies a read-only operation, the description discloses no behavioral traits regarding pagination, return format, caching, or authorization requirements.

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

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

Single sentence, front-loaded with the action and resource. No redundant words. The parenthetical efficiently qualifies the scope without wasting space.

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

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

Given the simple single-parameter schema and lack of output schema, the description adequately covers the core operation. However, it omits return value structure or pagination behavior that would help the agent handle the response.

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

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

With 100% schema description coverage (org_id is documented), the baseline is 3. The description adds no additional parameter context (syntax examples, format constraints) beyond what the schema provides.

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

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

The description uses specific verb 'List' with resource 'roles' and scope 'in an organization'. The parenthetical '(built-in and custom)' clarifies the result set, distinguishing it from siblings like sirr_role_create and sirr_role_delete.

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

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

The description states what the tool does but provides no explicit guidance on when to use it versus alternatives like sirr_principal_list or sirr_org_list. Usage is implied by the name but lacks prerequisites or exclusion criteria.

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

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. While the input schema notes that metadata 'replaces existing metadata' (destructive behavior), the main description omits this critical trait, along with any mention of authentication requirements, idempotency, or side effects.

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

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

The description consists of a single, efficient sentence that immediately states the tool's purpose without redundant language. While appropriately compact, this brevity contributes to the lack of behavioral and contextual details that would be necessary for a complete definition.

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

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

Given the absence of annotations and output schema, the description lacks necessary behavioral context (e.g., the destructive replacement nature of the update). However, for a single-parameter tool with complete schema documentation, it meets the minimum threshold of identifying the operation and target resource.

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

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

With 100% schema description coverage, the input schema fully documents the 'metadata' parameter including its structure and replacement semantics. The description merely references 'metadata' without adding syntax examples, valid key patterns, or usage context beyond the schema definition, warranting 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.

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

The description uses the specific verb 'Update' and identifies the resource as 'the current principal's metadata on the Sirr server'. It implicitly distinguishes from sibling tools like 'sirr_principal_create' (which creates other principals) by specifying 'current principal', though it does not explicitly contrast with 'sirr_me' which likely retrieves this data.

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

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

The description provides no guidance on when to use this tool versus alternatives, prerequisites for invocation, or conditions where it should not be used. It does not reference related tools like 'sirr_me' that might be queried before updating, or clarify when principal updates should be performed via other endpoints.

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

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

With no annotations provided, the description carries the full burden and succeeds by disclosing critical behavioral traits: it returns a webhook ID and signing secret, and explicitly warns that the secret is shown once and must be saved. Missing details on delivery retries, failure handling, or URL validation requirements prevent a 5.

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

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

Two sentences with zero waste: the first states purpose, the second discloses return values and the critical one-time secret warning. 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.

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

Given the absence of an output schema, the description appropriately explains the return values (webhook ID and signing secret) and includes the essential persistence warning. With 100% input schema coverage and clear behavioral context, the description is adequately complete for a webhook creation tool.

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

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

Schema description coverage is 100%, with the 'url' and 'events' parameters fully documented in the schema including examples. The description provides baseline semantic context ('Register a webhook URL') but does not add parameter-specific guidance beyond what the schema already provides, warranting the baseline score of 3.

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

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

The description clearly states the specific action (register), resource (webhook URL), and purpose (receive Sirr event notifications). It effectively distinguishes from sibling tools like sirr_webhook_delete and sirr_webhook_list by focusing on the creation/registration aspect.

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

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

The description implies the use case (receiving event notifications) but provides no explicit guidance on when to choose this over alternatives like polling, nor does it mention prerequisites such as URL accessibility requirements or authentication setup needed before invocation.

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

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

With no annotations provided, the description carries full burden but only states the deletion action without disclosing if the operation is permanent, whether pending deliveries are affected, or required authorization levels.

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

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

Single sentence of seven words is efficiently front-loaded with the action verb. No filler words or redundant information; every word earns its place.

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

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

Given the tool's simplicity (one required parameter, no output schema, no nested objects), the description covers the basic operation but lacks behavioral context (side effects, reversibility) that would be expected for a destructive operation.

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

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

Schema coverage is 100% with the 'id' parameter well-documented. The description references 'by its ID' but adds no additional semantic context (e.g., ID format, where to obtain it) beyond what the schema already provides.

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

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

The description uses specific verb 'Remove' with clear resource 'webhook registration' and scope 'by its ID'. It clearly distinguishes from siblings like sirr_webhook_create and sirr_webhook_list through the action verb alone.

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

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

While the naming convention and sibling tools imply the usage context, the description lacks explicit guidance on when to use this versus other webhook operations, or prerequisites like ownership verification.

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

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

With no annotations provided, the description carries the full burden. It successfully adds the critical behavioral detail that 'Signing secrets are redacted,' warning about sensitive data handling. However, it fails to explicitly confirm the read-only/safe nature of the operation that annotations would normally provide.

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

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

The description consists of two highly efficient sentences. The first establishes purpose; the second adds essential behavioral context (redaction). There is no filler or redundant information—every word earns its place.

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

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

For a simple list operation with no input parameters, the description is appropriately complete. It compensates for the missing output schema by noting the redaction of signing secrets, which is the primary implementation detail an agent needs to know. It could be improved by mentioning pagination or the read-only nature, but it is sufficient for invocation.

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

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

The input schema contains zero parameters. According to scoring rules, zero-parameter tools have a baseline score of 4, as there are no parameter semantics to describe beyond what the empty schema already communicates.

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

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

The description explicitly states the verb 'List' and the resource 'registered webhooks on the Sirr server', clearly distinguishing it from sibling list operations like list_secrets or sirr_key_list. It precisely defines the scope and target entity.

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

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

Usage is implied by the 'List' verb and webhook context (use when you need to see existing webhooks), but there is no explicit guidance on when to use this versus sirr_webhook_create or delete, nor any workflow prerequisites.

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