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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds minimal behavioral context beyond 'after approval'. It does not disclose constraints like file size limits, overwrite behavior, or failure scenarios.

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 sentence, making it concise but insufficiently informative. It lacks structured details and fails to earn its place with necessary information.

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 7 parameters, 6 required, and 0% schema coverage, the description is severely incomplete. It omits the approval workflow and required input semantics, leaving an agent unable to use the tool 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?

Schema description coverage is 0%, and the description does not explain any of the 7 parameters (e.g., approval_id, request_digest). The tool cannot be correctly invoked without parameter understanding.

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 tool adds attachment files to an incident after approval, specifying a distinct verb and resource. However, it does not fully clarify what 'after approval' entails, which could be ambiguous.

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 approval is a prerequisite but offers no explicit guidance on when to use this tool versus alternatives like add_comment or request_incident_action. No when-not-to-use or context is provided.

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?

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds the requirement of approval, which provides some behavioral context. However, it does not disclose other potential behaviors, such as whether the comment triggers notifications or modifies the incident state.

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 extremely concise (one short sentence). While this brevity is positive, it omits necessary details about parameters and behavior, making it less informative than needed for a tool with many parameters.

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 complexity (7 parameters, 6 required, presence of output schema), the description is too sparse. It fails to explain the approval workflow, comment content expectations, or how the tool integrates with other sibling tools like phishfort_request_incident_action.

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 7 parameters (6 required) with 0% schema description coverage. The description does not explain any parameter's purpose or constraints, leaving the agent to rely solely on parameter names and types, which are insufficient.

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 (add a comment), the resource (comment), and the context (to an existing incident after approval). It effectively distinguishes from sibling tools like phishfort_report_incident or phishfort_request_incident_action.

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 specifies that the tool should be used 'after approval,' providing a clear context. However, it does not explicitly state when not to use it or mention alternatives, leaving some ambiguity about its place in the workflow.

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?

Annotations (readOnlyHint=false, destructiveHint=false) indicate it's a non-read, non-destructive mutation. The description adds behavioral context about the one-time secret being saved locally and not returned, which is valuable but does not fully explain side effects, authorization, or idempotency nuances.

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 very short and front-loaded with the core purpose. Every sentence is useful, but it could be improved by adding more detail about parameters without becoming wordy.

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 complexity (9 params, 6 required, output schema exists but not detailed), the description is insufficient. It lacks information on return values, error states, and how to use the secret, making it hard for an agent to invoke correctly without additional knowledge.

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 0% schema description coverage, the description must compensate but only mentions the secret behavior, not explaining any of the 9 parameters (url, events, approval_id, etc.). This leaves parameter meaning entirely to the agent's inference.

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 it creates a webhook subscription and mentions the one-time secret behavior. It distinguishes from sibling webhook operations (list, update, delete, etc.) but could be more explicit about the context of PhishFort webhooks.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as prerequisites for using approval_id/approval_phrase, or when to prefer this over other webhook 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?

The description adds the behavioral note 'after approval', which is not in the annotations. However, with destructiveHint=true already declared, the description could further detail the destruction's reversibility, side effects, or the confirmation mechanism (destructive_confirmed parameter).

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 only eight words, which is under-specified rather than concise. It lacks essential information about parameters, usage, and output, making it ineffective despite its brevity.

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?

The tool has six parameters, an output schema, and a multi-step flow implied by 'after approval'. The description fails to explain any of these, leaving the agent without guidance on how to call the tool correctly.

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 0% schema description coverage, the description must explain the six parameters. It does not mention any parameter, including critical ones like webhook_id, approval_id, approval_phrase, expires_at, request_digest, or destructive_confirmed. This is a severe gap.

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 'delete' and the resource 'webhook subscription', with the qualifier 'after approval'. This is specific enough to distinguish from read operations, but it could be more explicit about what type of webhook or the approval context.

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 is provided on when to use this tool versus alternatives like phishfort_update_webhook or phishfort_test_webhook. The phrase 'after approval' hints at a precondition but does not specify scenarios, prerequisites, or when not to use it.

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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the behavioral note that the subject parameter is URL-encoded, which is useful. However, it does not disclose other behaviors such as what happens if no incident is found (e.g., returns null vs. error), but the annotations already cover the safety profile well.

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 succinct sentences with no filler. It directly states the purpose and a key encoding detail, making it efficient and easy to parse.

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?

The tool has low complexity (1 param, required) and an output schema exists, so return format is covered. However, the description lacks guidance on usage context and does not mention error conditions or edge cases, making it minimally complete for effective agent invocation.

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

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

The schema has 0% description coverage, so the description carries the burden. It adds meaning by stating that the subject parameter can accept a URL, domain, or subject value and that it should be URL-encoded. This provides some clarity beyond the schema, but the description is still vague about the exact format expected.

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 verb 'Find' and the resource 'incident', and specifies the search criteria (URL, domain, or subject value). However, it mentions multiple criteria while the schema only defines a single 'subject' parameter, which could cause confusion about how to provide URL or domain values.

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 is given on when to use this tool versus sibling tools like 'phishfort_list_incidents' or 'phishfort_get_incident'. There is no explicit when-to-use or when-not-to-use context, leaving the agent to infer usage from the name alone.

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?

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it does not fetch the document, which is consistent and provides additional context beyond 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?

Single sentence, front-loaded, no extraneous words. Efficiently conveys the tool's action and boundaries.

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?

With an output schema present, returning metadata and signed URL is sufficient. No critical gaps remain given the tool's simplicity and 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?

Schema coverage is 0%, meaning the parameter 'document_id' lacks description. The tool description does not explain the parameter's purpose, format, or required values. Agent must infer from name only.

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 clearly states it retrieves document metadata and a time-limited signed URL without fetching the document content. This distinguishes it from sibling tools like phishfort_get_document_signed_url which presumably only gets the URL.

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?

Description implies usage for metadata and URL retrieval but does not explicitly state when to use this tool over alternatives (e.g., phishfort_get_document_signed_url for just the URL). No negative guidance or context provided.

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?

Description adds behavioral context beyond annotations: 'time-limited' and 'without fetching it' clarify the URL's lifespan and that the document content is not returned. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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 conveys the core functionality with zero waste. 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?

Despite having an output schema, the description is too minimal. It does not mention any prerequisites, the meaning of 'time-limited', or how the URL is used. Combined with no parameter details, it leaves gaps for an AI agent.

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 0% and the description fails to explain the document_id parameter beyond its name. With only one parameter, minimal effort to describe its format or purpose would significantly improve clarity.

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 clearly states the tool generates a time-limited document URL without fetching the content. It distinguishes from phishfort_get_document (fetches content) and phishfort_list_documents (lists documents).

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 explicit guidance on when to use this tool versus alternatives. Does not mention that it's for sharing/accessing documents without downloading, nor when not to use it.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds no behavioral info beyond what annotations 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?

Single sentence, 6 words, front-loaded with verb and resource. No wasted words.

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?

Tool is simple with output schema, so return value is covered. However, no context on parameter usage or common use cases. Adequate but minimal.

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 0% description coverage, and the description does not explain the incident_id parameter or its format/meaning.

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 clearly states the action (Get), resource (PhishFort incident), and identifier method (by id). Distinct from sibling tools like phishfort_list_incidents and phishfort_find_incident_by_subject.

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 explicit guidance on when to use this tool versus alternatives. No mention of prerequisites or when not to use.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, fully covering safety behavior. The description adds no additional behavioral context (e.g., response format stability, pagination). It does not contradict 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?

A single, efficient sentence that conveys the exact purpose without any filler. 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, parameterless info tool with an output schema, the description is sufficient. It could mention common use cases (e.g., checking limits before other calls) but is adequate as-is.

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 zero parameters, and schema coverage is 100%. Per guidelines, 0 parameters yields a baseline of 4. No further parameter explanation is needed.

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 tool returns 'documented API limits and MCP-enforced limit choices', specifying a precise verb and resource. This distinguishes it from all sibling tools which focus on incidents, documents, users, 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?

No explicit guidance on when to use this tool vs alternatives is provided. However, the purpose is simple and distinct, so usage is implied. The description could benefit from a brief note like 'Use this before making API calls to avoid rate limiting.'

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns supported operations and mutation approval requirements, providing useful behavioral context beyond what annotations convey. 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?

The description is a single sentence that clearly and directly states the tool's purpose with no extraneous information. It is appropriately sized and front-loaded.

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 zero parameters and the presence of an output schema (not shown but declared), the description adequately covers the tool's function. It names the two key outputs (operations and mutation approval requirements), which is sufficient for a listing 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?

With zero parameters, schema coverage is 100%, so the baseline is 4. The description adds no parameter info, but none is needed. It correctly states what the tool does without parameter details.

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 tool lists supported PhishFort MCP operations and mutation approval requirements. It uses a specific verb ('list') and resource ('capabilities'), distinguishing it from sibling tools that perform CRUD operations.

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 usage for discovering available operations, but lacks explicit guidance on when to use vs alternatives or any exclusions. No sibling tool duplicates this function, so no conflict, but the description could be more explicit about its role.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond what annotations provide. The description does not contradict 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?

The description is a single, efficient sentence. It is front-loaded with the purpose, but lacks depth. It earns its place without waste.

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?

The tool has 5 parameters and an output schema. The description is minimal and does not cover parameter details, but the presence of an output schema reduces the burden for return value explanation. Some gaps remain.

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 0%, so the description must compensate. It merely lists parameter names without explaining their meaning, types, or allowed values. This is insufficient for effective tool use.

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 verb 'List' and the resource 'visible clients', and enumerates available filters. There is no sibling tool with similar purpose, so no differentiation needed.

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 description does not explicitly state when to use this tool versus alternatives, the name and purpose make it obvious. No exclusion criteria or alternative references are provided, but the context is clear enough.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, idempotent read operation. The description adds minimal behavioral info (only about doc_type). Without annotations, this would be a 2, but with annotations, the bar is lower. 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.

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

The description is extremely short at one sentence, which is concise but at the cost of completeness. It could be expanded to include essential details without becoming verbose. The structure is minimal, so it scores a middle mark.

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?

With 10 parameters, 0% schema coverage, and a complex tool, the description is far too minimal. It omits pagination, filtering, sorting, and output details. Although an output schema exists externally, the description should still provide enough context to select and invoke the tool correctly. It fails to do so.

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 0%, so the description must compensate. It only explains that 'doc_type accepts comma-separated documented types,' which adds meaning for one parameter. The other nine parameters (q, page, limit, sort_by, etc.) are left unexplained, failing to provide necessary semantics for correct invocation.

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 it lists document metadata, which is a clear action on a resource. However, it is vague—doesn't specify what types of documents or the tool's scope. It doesn't differentiate from sibling listing tools like phishfort_list_incidents. A more specific verb and resource description is needed.

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 on when to use this tool versus alternatives, or any prerequisites. With many sibling tools for listing (incidents, capabilities, etc.), the description should indicate that this is for listing documents specifically and suggest when to use other tools like phishfort_get_document for a single document.

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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds minimal behavioral info beyond paging. It does not disclose default ordering, response format, or any 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, but the first sentence is a tautology (repeats title). The second adds one useful detail. Could be more succinct.

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 7 parameters and no param descriptions, the description is grossly incomplete. An agent cannot determine how to filter incidents, what the output contains, or how pagination works beyond the include_total flag.

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 0% schema description coverage and 7 parameters, the description only explains 'include_total'. All other parameters (limit, cursor, status, dates, client_id) lack any semantic context, making it hard for an agent to use them correctly.

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

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

The description 'List incidents' clearly states the action and resource. It distinguishes from sibling tools like 'phishfort_find_incident_by_subject' or 'phishfort_get_incident' by indicating a listing 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?

No guidance on when to use this tool vs. alternatives. The only hint is to set include_total for paging, but no context on filtering or ordering.

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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the filters, but does not contradict annotations. Given annotation coverage, a score of 3 is appropriate.

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, concise, and front-loaded with the verb and resource. No redundant information, but could be expanded slightly for clarity without losing conciseness.

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?

With 5 optional parameters and no schema descriptions, the description lacks details on output, pagination behavior (limit/offset), search mechanism, and the meaning of filters. An output schema exists but is not referenced. The description is too sparse for a tool with this 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?

Schema description coverage is 0%, so the description must compensate. It only lists parameter names (role, client, search, limit, offset) without explaining values, formats, or semantics (e.g., what 'client' refers to, allowed roles). This is insufficient for agent understanding.

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 tool lists users with specific filters, distinguishing it from other list tools. However, it could be more precise about the user scope (PhishFort users) already implied in the title.

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 on when to use this tool versus sibling tools like phishfort_list_clients or phishfort_list_incidents. The description only lists filters without contextualizing use cases.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no extra behavioral context beyond stating it lists subscriptions, which is consistent with annotations. No contradiction.

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, no unnecessary words, directly conveys the tool's action.

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 operation (0 parameters), presence of output schema, and comprehensive annotations, the description is mostly complete. It could note that it returns a list of subscriptions, but this is implied.

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?

No parameters exist, and schema coverage is 100%. The description correctly omits parameter details as none are needed. Baseline score of 4 for parameter-free tools.

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

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

The description 'List configured webhook subscriptions' uses a specific verb (list) and resource (webhook subscriptions), clearly distinguishing it from sibling tools like create_webhook, delete_webhook, 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?

No explicit guidance on when to use this tool versus alternatives. The sibling names imply a listing role, but there is no mention of when to use list vs other webhook tools or when not to use it.

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?

The description says 'Does not mutate', but annotations have readOnlyHint=false, implying possible side effects (e.g., creating a plan object). This contradiction undermines transparency. No other behavioral details like authentication or rate limits are provided.

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 very short (two sentences) and front-loaded with the core purpose. Every sentence adds value, though it could be slightly expanded without losing conciseness.

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 having an output schema, the description lacks sufficient context for a planning tool with three parameters. It does not explain what 'planning' entails, how parameters affect the plan, or how to use the approval fields. More detail is needed for effective use.

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 description provides no information about the three parameters (params, operation, expires_in_seconds). With schema description coverage at 0%, the description fails to add any meaning beyond the raw schema, leaving the agent with minimal guidance.

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 tool's purpose: 'Plan a PhishFort write.' and adds 'Does not mutate.' which distinguishes it from actual mutation tools. This is a specific verb-resource combination that differentiates it from siblings like phishfort_report_incident.

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 gives clear usage context: it plans a write, does not mutate, and the output ('approval fields') should be used on write tools. However, it does not explicitly state when not to use it or contrast with other non-mutating tools among siblings.

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?

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the context of 'after approval' and the dual purpose (takedown or monitoring), which is useful but does not significantly expand behavioral disclosure beyond what annotations 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 single-sentence description is concise and front-loaded, but at the cost of clarity. It earns its place yet is insufficient for a tool with 13 parameters, making it adequately sized but not effectively informative.

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?

The tool is complex with many required parameters and an approval workflow, but the description lacks details about prerequisites, output, or parameter dependencies. With an output schema exists, but the description ignores it, leaving significant gaps.

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 13 parameters and 0% schema description coverage, the description must compensate but does not. It provides no explanation for any parameter (e.g., 'action', 'approval_id', 'destructive_confirmed'), leaving agents to guess their meaning and usage.

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 tool reports an incident for takedown or monitoring after approval, which provides a verb and resource. However, it does not clearly differentiate from sibling tools like phishfort_request_incident_action or phishfort_add_comment, leaving ambiguity about its exact role.

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 is provided on when to use this tool versus alternatives. The description only mentions 'after approval' as a precondition, but does not specify when or why this tool should be chosen over similar sibling tools.

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?

Annotations indicate destructiveHint=true, and the description lists three actions including 'takedown' (destructive) and others. However, it fails to mention the required approval process and the 'destructive_confirmed' parameter, which are important behavioral traits beyond what annotations 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 is very short (9 words), but it under-specifies the tool's behavior and parameters. It is not efficiently informative; the brevity sacrifices clarity and completeness.

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 complexity (7 params, destructive hint, approval flow), the description is severely incomplete. It does not explain the purpose of each parameter, the approval mechanism, or the output. Although an output schema exists, the input side is barely 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?

The input schema has 0% description coverage, so the description must compensate. It does not describe any parameter meanings, value options for 'action', or the purpose of approval-related fields. The tool has 7 parameters, and the description adds no semantic value.

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 tool requests takedown, monitoring, or safe review for an existing incident. It uses a specific verb ('request') and specifies the resource (existing incident) and action types, distinguishing it from siblings like 'report_incident' which creates new incidents.

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 usage context (requesting an action on an existing incident) but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. It relies on the agent to infer that this is for modifying an incident's state.

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?

Annotations already indicate destructiveHint=true. The description adds that the secret is saved locally and not returned, which informs the agent about side effects (loss of secret in response). However, it does not disclose other behavioral traits like the need for approval or that the action is irreversible.

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 very short (one sentence) and front-loaded. However, given the complexity of the operation (7 params, destructive, requires approval), it is underspecified. The sentence is efficient but insufficiently structured for a tool with many parameters.

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?

The description lacks critical context: it does not explain the approval flow, the meaning of parameters, or what success looks like. The existence of an output schema is implied but not described. For a destructive tool with many required parameters, this is incomplete.

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 0% schema description coverage and 7 parameters (5 required), the description adds no meaning to the parameters. It does not explain what 'webhook_id', 'approval_id', 'approval_phrase', 'expires_at', 'request_digest', 'secret_output_name', or 'destructive_confirmed' represent. The agent must guess or consult external docs.

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 'Rotate webhook secret', clearly identifying the action (rotate) and resource (webhook secret). It distinguishes from create/update/delete webhook siblings by focusing on secret rotation. The addition 'One-time secret is saved locally, not returned' adds clarity, though it could elaborate on the rotation process.

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 update_webhook. There is no mention of prerequisites, context, or scenarios where rotation is appropriate. The agent must infer usage from the name alone.

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?

Annotations indicate destructiveHint=false, readOnlyHint=false, but the description only says 'send test webhook delivery', which is vague. It does not disclose potential effects like whether the test modifies state or triggers real callbacks, nor does it add context beyond the 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?

The description is extremely short (one sentence), which is under-specified rather than concise. It lacks essential information and does not justify its brevity with adequate coverage of the tool's purpose or usage.

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?

With 5 required parameters and no parameter descriptions, the tool is highly complex but the description provides virtually no context. Despite having an output schema (not shown), the description fails to explain what the test does, what errors might occur, or how to interpret 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 0% with 6 parameters, and the description provides no explanation of any parameter. It fails to add meaning beyond the schema's basic type/title fields, leaving the agent with no understanding of what each parameter represents.

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 name 'phishfort_test_webhook' and description 'Send test webhook delivery after approval' clearly indicate the tool's function: testing a webhook. It is specific about the action and resource, but does not differentiate from siblings like phishfort_create_webhook or phishfort_list_webhooks.

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 says 'after approval', implying a prerequisite, but provides no explicit guidance on when to use this tool vs alternatives, such as when to test vs. verify or other webhook operations. No exclusions or context are given.

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?

Annotations already indicate this is a non-read-only, non-destructive write operation. The description adds only the unhelpful detail 'after approval' without explaining the approval process, idempotency, side effects, or authentication requirements. For a tool with a complex approval workflow, this is insufficient behavioral context.

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

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

The description is a single concise sentence, but it sacrifices informative content for brevity. It front-loads the update action but omits essential details, making it less efficient than a longer but more complete description.

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 complexity (10 parameters, 5 required, approval workflow, and an output schema), the description is grossly incomplete. It fails to mention what the tool outputs, what fields can be updated, or the approval process. The agent would need to inspect the schema extensively to invoke the tool correctly.

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 0%, meaning the description provides no information about any of the 10 parameters (5 required). The unique approval-related parameters (approval_id, approval_phrase, request_digest) are not explained, leaving the agent to guess their purpose. This is a critical failure for correct tool invocation.

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 'Update webhook subscription after approval,' which clearly identifies the verb (update) and resource (webhook subscription), and hints at a prerequisite (approval). However, it does not distinguish this tool from sibling tools like phishfort_create_webhook or phishfort_delete_webhook, nor does it specify which webhook fields can be updated.

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 'after approval' implies a precondition but provides no explicit guidance on when to use this tool versus alternatives (e.g., create or delete). There are no statements about when not to use it, prerequisites (e.g., existing webhook), or exclusions. With many sibling tools, this lack of guidance is a significant gap.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds minimal context about using a local secret file but does not disclose verification logic, error handling, or implications of invalid signatures.

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, well-structured sentence that immediately conveys the action and key constraint. No redundant or extraneous words.

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 having 4 required parameters and an output schema, the description is too brief. It omits important context such as return value interpretation, error cases, and how to prepare the secret file, making it incomplete for reliable usage.

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 0% schema description coverage, the description should compensate but only hints at 'fresh' (timestamp relevance) and 'local secret file' (secret_file). It does not explain raw_body, signature format, or secret_file content, leaving significant ambiguity.

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 tool verifies a fresh X-PhishFort-Signature using a local secret file. The verb 'verify' and resource 'signature' are specific, and the tool is distinct from all sibling tools which focus on CRUD operations on incidents, documents, users, and webhooks.

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 does not specify when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It lacks guidance on context, such as after receiving a webhook event.

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?

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds that it returns identity, but doesn't disclose additional behavioral traits beyond what annotations convey. 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?

Single sentence, no unnecessary words. Front-loaded purpose. Perfectly concise for a zero-parameter tool.

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?

With zero parameters and an output schema (implied), the description is complete. It tells the agent exactly what the tool does without needing added explanation.

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?

No parameters, so baseline is 4. Description doesn't need to add parameter info; schema coverage is trivially 100%.

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 clearly states the tool returns the authenticated PhishFort client identity. It uses a specific verb ('Return') and resource ('authenticated PhishFort client identity'), distinguishing it from sibling tools that handle incidents, documents, webhooks, 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?

No explicit guidance on when to use this tool or alternatives. For a simple identity retrieval, the description is adequate but could mention it's for verifying client identity or checking authentication status, especially given many sibling tools.

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