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

The description discloses meaningful behavioral traits beyond the minimal annotations: values can be overridden per environment, set_config_value can auto-declare keys later, and parent enables inheritance. It does not contradict annotations. It doesn't mention edge cases like overwriting existing configs or permissions, but it adds substantial 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?

Two short, purposeful paragraphs. The first sentence delivers the core definition, and the rest expands on usage variations. Every sentence adds unique value with no filler or 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?

Given the tool has an output schema (which likely documents return values), the description fully covers the key creation decisions: seeding items, leaving empty, and parent inheritance. It also clarifies the relationship with set_config_value, making it complete for a create 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%, so the baseline is 3. The description adds value by explaining the purpose of 'items' and 'parent' in context, improving understanding beyond the schema's own field descriptions. It doesn't need to expand config_id or description since the schema already covers them.

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 'Create a named config: a keyed collection of typed values your code reads at runtime,' which clearly states the verb, resource, and purpose. It distinguishes create_config from sibling tools by explaining what a config is and how it relates to set_config_value.

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?

Explicit guidance is given: 'Seed the starting keys here via `items`, or create the config empty and let set_config_value auto-declare keys later' and 'Use `parent` to inherit another config's keys.' This indicates when to use this tool and the optional approaches, though it doesn't explicitly contrast with unrelated 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 already indicate this is a mutating (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds useful context that create_flag only establishes the flag with a default, while per-environment values and targeting belong to set_flag. This clarifies the tool's scope beyond the 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?

The description is two sentences, front-loaded with the primary purpose and required core inputs, followed by a single actionable next step. Every sentence earns its place with no redundancy or fluff.

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 a straightforward create operation with a fully described input schema and an output schema. The description appropriately states what the tool creates and points to the next operation (set_flag) for further configuration, making it complete for an agent to select and invoke 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?

The input schema covers all six parameters with detailed descriptions, so the schema itself is the primary source. The description only restates 'type, key, and default' without adding new semantic detail or usage nuances for the parameters, so it doesn't exceed the schema's baseline.

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 action, 'Create a feature flag', and names the required inputs (type, key, default value). This clearly differentiates it from siblings like get_flag, set_flag, and delete_flag, which perform different operations on the same 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?

The description provides a clear follow-up direction: 'After creating, use set_flag to set per-environment values and targeting.' This tells the agent what to do next and implicitly distinguishes create_flag from set_flag, though it does not cover more general when/when-not scenarios or alternatives.

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 convey the write and non-destructive nature. The description adds the public-reachability constraint, but does not disclose behaviors like validation failure, whether it contacts the destination, or response details.

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 concise sentences, front-loaded with the purpose, followed by a prerequisite. 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?

With a full input schema and an output schema present, the description is sufficient. It could add a bit more about the forwarder_type options or filter semantics, but those are already in the schema. The usage tip adds helpful context.

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 covers 100% of the 12 parameters with descriptions, so baseline is 3. The description adds no parameter meaning beyond what schema already provides; the URL reachability note is repeated.

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 'Wire a forwarder' and clearly states its function: delivering audit events to a SIEM/HTTP destination. It distinguishes from sibling tools like test_forwarder and delete_forwarder by indicating 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?

It provides explicit guidance: 'Prove the destination first with test_forwarder' and states a required condition ('URL must be reachable from the public internet'). This tells the agent when to use and what to do before creating.

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 only indicate readOnlyHint=false and destructiveHint=false. The description adds non-obvious behavior: the kind is inferred (with instructions 'never set it yourself'), and it explains when jobs run based on parameters. It also states the URL must be publicly reachable, which is a critical operational constraint.

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 compact and well-structured with bullet points. Every sentence adds value: the opening defines the tool, the bullets clarify the three modes, and the final sentences give important prerequisites and recommended follow-up. No fluff or 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?

Given the tool has 12 parameters and an output schema, the description doesn't need to explain return values. It covers the essential non-schema context: job kind inference, manual vs. scheduled behavior, public URL requirement, and the run_job verification step. It could mention mutual exclusivity of schedule/run_at, but the schema already does that.

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 parameters are already well documented. The description adds a concise synthesis of the schedule/run_at/neither modes, which complements the schema but doesn't add significant detail beyond it. Most parameter semantics are already in the schema, so this is a minimum-viable score.

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 begins with 'Create a scheduled HTTP job,' which is a specific verb+resource that clearly distinguishes this tool from siblings like list_jobs, update_job, and run_job. It further elaborates on three job kinds (recurring, one-off, manual), making the tool's purpose unambiguous.

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 explicitly states that the job kind is inferred from schedule/run_at and advises calling run_job after creating a recurring job to verify it works. It also notes the URL must be publicly reachable. While it doesn't explicitly contrast with update_job or delete_job, the usage 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?

While annotations already mark this as destructive, the description adds key behavioral details: there is no undo, and SDKs fall back to code-level defaults after deletion. This explains the operational impact beyond the abstract destructiveHint flag.

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 the main action first and supporting details (no undo, fallback, alternative) following. No wasted words; each clause conveys necessary information about the delete operation's consequences and 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?

For a destructive mutation tool, the description covers permanence, fallback behavior, and the alternative for partial updates. The presence of an output schema handles return-value documentation, so nothing essential is missing.

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 fully describes config_id as 'The config's key' (100% coverage). The description does not add parameter-specific guidance beyond that, but it is consistent with the schema's meaning. Baseline 3 applies given full 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 opens with 'Permanently delete a config and all of its keys and per-environment values,' which is a specific verb+resource+scope. It also distinguishes from the sibling tool set_config_value by noting 'instead of deleting the whole config,' making the purpose unmistakable.

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 explicitly states when to use an alternative: 'To change or clear a single value, use set_config_value instead of deleting the whole config.' It also covers the recovery path via create_config and the consequence of permanent deletion, giving clear 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?

Beyond the annotations' destructiveHint=true, the description details consequences: permanent deletion, no undo, impact on SDKs serving defaults, and loss of per-environment values/rules. This discloses exactly what gets destroyed and the post-delete behavior, exceeding what annotations alone 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?

Three sentences: the first states the action, the second states irreversibility and recovery, the third covers the alternative. No filler, every sentence adds critical information, and the most important fact (permanent delete) is 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?

The destructive nature carries significant side effects; the description addresses what gets deleted, irreversibility, post-delete SDK behavior, and recommends an alternative. This fully equips an agent to safely invoke the tool and reason about its outcomes.

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 already fully describes the single key parameter (100% coverage), so the baseline is 3. The description references the key but adds no new syntax or format details 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 'Permanently delete a flag and all of its per-environment values and rules,' clearly identifying the action (delete), target (flag), and scope (all values/rules). This distinguishes it from sibling tools like set_flag (which toggles) and create_flag (which recreates).

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 explicitly contrasts with set_flag: 'prefer set_flag with enabled=false' for the non-destructive kill-switch use case, and mentions create_flag for recreation. This gives an agent clear decision guidance for when to use this tool versus alternatives.

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 transparency by stating that past forwarded events are unaffected, which is not captured by the destructiveHint annotation alone. This gives the agent important context about the consequences of deletion beyond the simple destructive flag. 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 concise, using two short sentences that pack the core purpose and a key behavioral caveat. Every sentence earns its place, and there is no redundancy or verbosity.

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 deletion tool with a single parameter and an output schema (not shown), the description adequately covers the purpose and an important side effect. It does not explain return values, but that requirement is waived when an output schema exists. The description is sufficient for the agent to select and 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?

The input schema already provides a complete description for the single parameter (forwarder_id as 'The forwarder's key.'), so the description does not need to add more. It adds no additional semantic detail beyond what the schema states, but since schema coverage is 100%, a baseline score of 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?

The description clearly states the action ('Delete a forwarder') with a specific verb and resource, and the added nuance about past forwarded events distinguishes it from related tools like create_forwarder or test_forwarder. It leaves no ambiguity about what the tool does.

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 usage context: you would use this tool to delete a forwarder. It does not explicitly mention alternatives or when not to use it, but given the straightforward verb+resource and the presence of sibling tools like create_forwarder, the intended usage is clear. The note about past events adds relevant behavioral 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?

Annotations already indicate destructiveHint=true, so the description's note that run history is retained and the id may be reused adds valuable behavioral context beyond the annotation. This is a non-obvious side effect of deletion that the agent would otherwise not know.

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 two sentences: the first states the core action, and the second adds a critical behavioral detail. No wasted words, and the most important information is front-loaded.

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

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

The tool is simple with one parameter, an output schema, and destructive annotations. The description provides the key additional context (retention of run history and id reuse) that an agent needs to understand the tool's behavior fully. No 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?

The input schema has 100% coverage for the single required parameter job_id, with a clear description. The tool description adds no additional parameter-level information, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a job' with a specific verb and resource, distinguishing it from sibling tools like delete_forwarder, delete_flag, and delete_config. The additional detail about run history retention and id reuse further clarifies the tool's scope.

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 by noting that run history is retained and the id may be reused, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. For a simple resource-specific deletion, this is acceptable but not fully explicit.

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 and openWorldHint: false, and the description does not contradict these. It adds context about the return content ('items plus per-environment overrides') but does not disclose other behaviors such as error handling or permissions. Given the annotations cover the safety profile, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence that concisely states the tool's purpose and return scope without any unnecessary words or repetition.

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 getter with one parameter and an output schema, the description provides essential context: it retrieves a specific config's full state including items and overrides. It does not cover error conditions or ID format details, but given the tool's simplicity and existing annotations/schema, it is adequately 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 coverage is 100% (config_id described as 'The config's key.'), and the description adds no additional meaning to the parameter. The baseline of 3 is appropriate since the schema fully documents the parameter.

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 'Get one config's full state: items plus per-environment overrides' states a specific verb (Get) and resource (one config), and clearly distinguishes it from sibling tools like list_configs or get_flag by specifying the full state including items and per-environment overrides.

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 (when you need a single config's full state) but does not explicitly mention alternatives or exclusions. There is no guidance on when not to use it or how it compares to list_configs or set_config_value.

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 and openWorldHint=false. The description adds value by enumerating the returned fields (actor, resource, event type, etc.) and noting the `data` payload, giving the agent a clear expectation of the response content without contradicting 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 two short paragraphs: the first states purpose, the second lists return details and usage guidance. Every sentence contributes, with no redundancy or 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?

For a simple one-parameter read tool with an output schema, the description fully covers purpose, parameter sourcing, workflow, and return contents. It is complete without needing to restate the 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?

The input schema already describes event_id as 'from query_events results' with 100% coverage. The description reiterates this source but does not add new semantic detail beyond the schema, so it meets the baseline for a well-documented parameter.

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 ('Fetch') and resource ('audit event') with clear scope ('by id, with its full detail'). It distinguishes from siblings by referencing query_events as the way to find IDs and positioning itself as the drill-down 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?

Explicitly instructs to use query_events first to obtain an event ID, then use this tool to drill into a single event. This provides clear when-to-use guidance and connects to the sibling 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?

The readOnlyHint annotation already indicates this is a safe read operation, and the description does not contradict this. It adds that the tool returns 'values plus targeting per environment,' which is useful but largely redundant given the output schema. No additional behavioral traits like permissions, rate limits, or error cases are disclosed.

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 is succinct and front-loaded, conveying the tool's purpose and output content without any filler 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?

For a simple read-only tool with one parameter, an output schema, and clear annotations, the description is largely complete. It covers the main purpose and return scope, though it lacks explicit usage guidelines or edge-case behavior. This is adequate 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?

The input schema already fully describes the single required 'key' parameter with 100% coverage, and the description does not add any additional formatting or usage details for it. Baseline score of 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?

The description clearly states 'Get one flag's full config' with specific output details ('values plus targeting per environment'). This distinguishes it from sibling tools like list_flags (which lists all flags) and set_flag (which updates).

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 this tool is for retrieving a single flag's full configuration, but it does not explicitly mention when to use it instead of list_flags or other alternatives. No exclusions or alternative tool references are 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?

The description adds context beyond the readOnlyHint annotation by specifying the contents of the returned configuration (schedule, target request, environments). It does not contradict annotations and provides a clear picture of what the read operation yields, though it doesn't cover potential edge cases or output format details (covered by output schema).

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 front-loads the core action and then parenthetically lists the configuration contents. Every word contributes meaning, and there is no redundancy or 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?

For a simple one-parameter getter tool with a readOnlyHint annotation and an output schema, the description is sufficiently complete. It conveys the purpose and scope of the operation, and the structured schema covers parameters and return values, leaving no critical 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?

The single parameter job_id is fully described in the schema ('The job's id.'), and schema description coverage is 100%. The description does not add any additional parameter semantics beyond confirming it retrieves one job, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get one job's full configuration' with a specific verb, resource, and scope. It distinguishes itself from sibling tools like list_jobs (which lists jobs) and create/update/delete_job by focusing on retrieving a single job's detailed configuration.

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 when one needs a specific job's configuration, but it does not explicitly state when to use this tool versus alternatives. There is no mention of exclusions or when to prefer list_jobs or get_run, making the guidance only implied rather than explicit.

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

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

Annotations already indicate readOnlyHint=true, and the description adds useful context: it returns account-wide default level and per-environment overrides, and notes that logger keys are dot-separated. This goes beyond the minimal safety profile, though it doesn't describe error behavior or what happens if the logger_id is invalid. Given the simple read-only nature, this is adequate.

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 three sentences, each earning its place: the first states the core function, the second provides usage context, and the third explains key formatting and a discovery tool. It is concise, front-loaded, and free of unnecessary detail.

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 parameter, read-only, with an output schema present), the description covers the essential aspects: what it retrieves, when to use it, and how to format the parameter. No additional information like pagination or return format is needed because the output schema handles that. This is complete for the context.

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 fully describes logger_id with 100% coverage: 'The logger's dot-separated key (e.g. 'sqlalchemy.engine').' The description repeats this format but does not add new semantic information beyond reinforcing it. Since the schema carries the burden, a 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?

The first sentence clearly states the tool's function: 'Get one logger's configuration: its account-wide default level and per-environment overrides.' This specifies the verb, resource, and scope, distinguishing it from sibling tools like list_loggers (which lists all loggers) and set_log_level/reset_logger (which modify levels).

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 explicitly says 'Use it to check the current level before or after set_log_level / reset_logger,' providing a direct use case and related tools. It also mentions list_loggers for discovering existing keys, giving an alternative for a different need (listing). This is clear guidance on when to use this tool versus others.

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, so the safety profile is known. The description adds value by disclosing the output structure (captured result with status, headers, body, truncation flag) and that it includes timings and failure reason—behavioral details not present in 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 short sentences, with the core purpose in the first and useful context about the captured response in the second. No filler or redundant 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?

With a single parameter and an output schema available, the description provides all necessary behavioral context: what the run contains, what data is returned, and how to think about the captured result. Annotations cover the read-only nature, so nothing is missing.

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 fully covers the only parameter (run_id, a UUID) with 100% description coverage. The tool description does not add extra meaning about the parameter, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Get one run' and lists the exact data returned (status, timings, failure reason, captured HTTP response). This distinguishes it from sibling tools like list_runs (single vs list) and get_job (run vs job).

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 contextual guidance ('This is where "what did it return?" lives'), implying it is the tool to use when you need the captured response details. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 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?

With readOnlyHint already declaring safety, the description adds context about the returned data (keys and per-environment values). However, it does not disclose behaviors such as pagination, default limits, or result ordering.

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 that is front-loaded with the core purpose. Every word adds value, with no redundancy or fluff.

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 simple with optional filters and an output schema present. The description adequately conveys the return content. It lacks mention of potential pagination or default behavior, but these are partially covered by the schema 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 100%, with each parameter described. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (list), the resource (configs), and the content (keys and per-environment values). It distinguishes from sibling tools like get_config (single config) and create_config (mutation).

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 listing configs, but it does not explicitly mention when to prefer this over alternatives like get_config or when to use the filters. No exclusions or alternative guidance 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 already declare readOnlyHint=true, so the description adds the 'valid targets' semantic and account scope. It does not describe pagination or formatting, but with a read-only annotation and output schema this is acceptable. 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 a single sentence that is information-dense and front-loaded, with no filler or redundancies.

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 read-only list tool with an output schema and fully documented parameters, the description covers the essential purpose and provides contextual value ('valid targets for set_* tools'). It does not need to explain return values since an output schema exists.

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 detailed descriptions for limit, search, managed, and classification. The description adds no parameter-specific information, so the baseline score of 3 applies.

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 'List' with the resource 'environments', scoped to 'the account's environments', and adds functional context—'valid targets for every set_* tool'—which clearly distinguishes it from sibling list tools like list_forwarders and list_jobs.

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?

It states that environments are the valid targets for set_* tools, implying when to use this tool (to find valid targets before calling a set tool). It does not explicitly mention alternatives or exclusions, but there are no direct sibling environment tools, so the context is clear.

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=true and openWorldHint=false, so the safety profile is known. The description adds meaningful context by specifying that results include per-environment state, which goes beyond the plain 'list' action. It does not describe pagination or sorting, but given the annotations and output schema, the disclosure is adequate.

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 that conveys the core purpose and a key output detail. No filler or redundancy exists, and the most important information is front-loaded.

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

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

Given the simple nature of a list operation with four optional parameters, the schema documents all params, and an output schema exists, the description is nearly complete. It lacks an explicit statement about whether all flags are returned by default (e.g., 'all' vs. paginated), but this is a minor gap given the overall context.

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 each parameter (type, limit, search, managed) having a clear description. The tool description itself adds no parameter information, but the schema fully carries that burden, so a baseline score of 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?

The description uses a specific verb ('List') and a clear resource ('feature flags') with an additional qualifier ('with their per-environment state'), making the tool's purpose unambiguous. It distinguishes from sibling tools like get_flag (single flag retrieval) and list_environments (lists environments, not flags).

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 clearly implies the tool is for listing all feature flags, but it does not explicitly state when to use it vs. alternatives like get_flag for a single flag, or filter by type. There are no exclusions or alternative tool mentions, leaving usage guidance to inference rather than explicit direction.

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 annotations already declare readOnlyHint=true, so the description's 'per-environment enablement' detail adds useful context about what the list includes. However, it doesn't disclose behaviors like pagination, default limit, or how enablement is represented, leaving the description to rely on the schema and output schema for those details.

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, clear sentence with no filler. It front-loads the action ('List') and resource ('SIEM forwarders') and efficiently includes the 'per-environment enablement' scope.

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 tool with full schema coverage and an existing output schema, the description provides adequate context by mentioning the per-environment enablement aspect. It does not need to explain return values since the output schema exists, and the read-only annotation covers safety 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%, with both limit and forwarder_type described in the input schema. The description does not add any additional meaning beyond what the schema already provides, so it receives 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 verb 'List' with a specific resource 'SIEM forwarders' and adds the scope 'per-environment enablement', making its function clear. This distinguishes it from sibling create, delete, and test tools.

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 clearly implies when to use this tool (when you need to list forwarders and their enablement), but does not explicitly mention alternatives or exclusions. The context is straightforward and the read-only nature is evident, so it earns a 4 for clear context without exclusions.

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?

While annotations declare readOnlyHint=true, the description adds meaningful behavioral context beyond the annotation by explaining that jobs are enriched with a `last_run` summary including status and captured HTTP status. This gives the agent insight into what the response will contain without relying solely on the output schema.

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 concise and front-loaded, with two sentences that immediately state the purpose and usage. Every sentence adds value, and there is no redundant or filler content.

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 tool with an output schema and a read-only annotation, the description is complete. It covers what the tool does, when to use it, and the enrichment behavior, leaving no significant gaps for the agent to infer.

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 provides 100% coverage for all three parameters (kind, name, limit), each with a description. The tool description does not add additional parameter semantics, but the schema already does the heavy lifting, so a baseline score of 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?

The description clearly states the tool's function: 'List the account's configured jobs, each enriched with its latest run.' It uses a specific verb ('List') and identifies the resource ('configured jobs'), and the enrichment detail helps distinguish it from sibling tools like list_runs or get_job.

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 use case: 'Use this to see what's scheduled and whether each job's most recent run succeeded or failed.' It doesn't explicitly mention alternatives or exclusions, but the context makes it obvious when to use this tool over others.

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, so the description isn't needed for safety. It adds value by disclosing that results include both managed and discovered loggers, and that account-wide and per-environment levels are shown. This goes beyond the annotation and helps the agent understand the tool's output composition.

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 three sentences long, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and clearly separates the main function, additional details, and use case.

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 list tool with an output schema and four optional parameters, the description covers the essential aspects: what is returned, the managed/discovered categorization, filtering options, and how the results can be used. It is complete for an agent to decide when to invoke it.

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 parameters are fully documented already. The description adds minimal extra meaning, only reinforcing that 'managed' can be used as a filter. This doesn't significantly exceed the schema's own descriptions, so 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?

The description clearly identifies the tool as listing loggers known to smplkit, including their levels. It uses a specific verb ('List') and resource ('loggers'), and distinguishes itself from siblings like get_logger (singular) and set_log_level by focusing on discovery of 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?

Provides clear context for when to use the tool: to discover dot-separated logger keys for later use with set_log_level. It also explains the managed/discovered distinction and mentions filtering with 'managed'. It does not explicitly state when not to use alternatives, but the intended workflow is clear.

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 and openWorldHint=false. The description adds valuable behavioral context by characterizing the tool as a 'pull-based monitoring path' and explaining that failed_only is a shortcut for status=FAILED. It does not contradict annotations, and it does not need to restate safety hints.

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 two sentences and front-loads the core purpose. Every phrase earns its place, and it avoids repeating schema or annotation details. It is concise yet 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?

Given the tool has 9 optional parameters but a 100% schema description and an output schema, the description covers all major filter dimensions ('job, status, trigger, environment, and/or time window') and gives a real usage scenario. Nothing essential is missing for an agent to invoke it 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 coverage is 100%, so the baseline is 3. The description elevates this by giving practical meaning to failed_only (answers 'has anything failed?') and job (shows one job's history), which helps an agent choose filters correctly beyond the schema's literal 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?

The description uses a specific verb ('List') and states the exact resource ('runs') plus the filter dimensions (job, status, trigger, environment, time window). It clearly distinguishes itself from sibling tools like get_run by focusing on listing/filtering rather than retrieving a single run.

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 explicitly frames the 'pull-based monitoring path' with failed_only=true or status=FAILED for checking failures, and job=<id> for a single job's history. It gives clear usage context but does not explicitly state alternatives or when not to use the tool, such as referencing get_run for individual run details.

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?

Beyond the readOnlyHint annotation, the description discloses additional behavioral traits: the audit log is immutable, results are returned newest-first, filters combine with AND, and the tool is read-only. This goes well beyond what annotations alone provide, giving clear expectations for the agent.

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 three sentences: the first states purpose, the second covers ordering and filter combination, and the third gives an example and points to the sibling tool. Every sentence earns its place, and the most critical information is front-loaded. It is concise and well-structured.

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 12 optional parameters and an output schema, the description appropriately covers the essential behaviors: filter combination, ordering, read-only nature, and an example. All parameter semantics are provided via the schema, so the description does not need to repeat them. It is complete for an agent to select and 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 coverage is 100%, so the baseline is 3. The description adds valuable semantic context beyond the schema by explaining that filters combine with AND and by providing an illustrative example with resource_type and since. This additional information enriches the meaning of parameters without duplicating schema 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 searches the immutable audit log, answering 'who changed what, and when?'. The verb 'search' and resource 'audit log' are specific, and it distinguishes itself from the sibling tool get_event by instructing users to use get_event to drill into a single event.

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 usage guidance: filters are optional and combine (AND), calling with no filters shows most recent activity, and it gives a concrete example. It also points to get_event as the alternative for drilling into a single result, satisfying the when-to-use vs. alternatives criterion.

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 destructive and non-read-only behavior. The description adds detail that a config is deleted and the logger reverts to default, clarifying the exact effect beyond the annotation flags. No contradiction found.

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 that front-loads the purpose. Every part of the sentence earns its place with 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 simple tool with one well-described parameter, an output schema, and clear annotations, the description sufficiently explains the action and effect. It does not cover edge cases like idempotency or missing logger, but that is not essential given the tool's simplicity.

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 already provides a clear description for logger_id ('dot-separated key') with 100% coverage. The tool description adds no additional parameter meaning, so baseline 3 applies.

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: 'Stop managing a logger — delete its config so it reverts to the default.' It specifies the verb 'delete' and the resource 'config,' making it distinct from siblings like set_log_level or get_logger.

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 context on when to use the tool: when you want to stop managing a logger. It implies usage for reverting to default configuration, though it does not explicitly exclude alternatives or name 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?

The description discloses that it returns the run's status plus captured HTTP response (status, headers, body) upon completion, and that schedule/enabled state are unchanged. Annotations already indicate non-read-only and destructive hint, and the description adds clarity on what exactly is affected and what is returned.

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 short sentences/paragraphs, front-loaded with the action and result, no filler. Wastes no 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?

Given the output schema exists, description adequately covers purpose, behavior, and side effects. It doesn't explain error cases, but for an immediate-run tool, this is sufficient.

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 for all three parameters with descriptions. Description doesn't add any parameter-specific semantics beyond what the schema already provides, so baseline 3 holds.

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 'Fire one immediate run of a job and return the captured result', which is a specific action on the job resource. It distinguishes from sibling tools like create_job/delete_job by focusing on executing the job, and from list_runs/get_run by producing a new run and returning its captured response.

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 'This is the way to prove a job works' gives a clear use case, and the clarification that 'schedule and enabled state are unchanged' implicitly tells the user not to use this for configuration changes (use update_job). It doesn't explicitly name alternatives, 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?

The description goes well beyond the destructiveHint annotation by explaining the full workflow: reads config, sets override, saves full config, and preserves other keys/environments. It also discloses the auto-declaration behavior for keys, which is not evident from the schema or 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 three sentences long, front-loads the purpose, and every sentence conveys essential behavioral information. There is no repetition, fluff, or redundant schema restating.

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 output schema and annotations, the description covers the tool's behavior comprehensively: what it does, its side effects (preserving other keys/environments), and edge cases (auto-declaration of keys). No critical information is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the key is auto-declared (type inferred) if not already defined, providing meaning beyond the schema's simple field descriptions. This slightly elevates the score.

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 'Set one config key's value in one environment,' which is a specific verb+resource+scope. It clearly distinguishes this from sibling tools like get_config, delete_config, and set_flag by focusing on a single config key in a single environment.

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 context by explaining the read-modify-save behavior and noting that other keys and environments are preserved. It does not explicitly mention when not to use this tool or name alternatives, but the context makes the intended use obvious.

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?

Beyond the destructiveHint annotation, the description discloses that the tool reads, applies changes, and saves the full flag to preserve other environments. This adds valuable behavioral context without contradicting 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 three sentences with the purpose front-loaded. Every sentence contributes meaningful information, with no redundancy or fluff.

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 and detailed parameter schemas, the description sufficiently covers the core behavior and partial-update semantics. It could mention the destructive potential of specific arguments, but the schema already covers that nuance.

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 provides 100% coverage with detailed descriptions for all parameters. The description reinforces the optionality of parameters ('Pass only what you want to change'), but adds little beyond what the schema already states.

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 'Set a flag's value, kill switch, and targeting in one environment,' using a specific verb and resource. This distinguishes it from sibling tools like create_flag, get_flag, and delete_flag, making the purpose unambiguous.

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 explains the read-modify-write behavior and that you can 'Pass only what you want to change,' which guides partial updates. It doesn't explicitly state when not to use (e.g., for creating a new flag), but the context is clear enough given sibling tool names.

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 and readOnlyHint=false, so the description adds value beyond that with 'creates the logger if needed' and 'Other environments are preserved'. It clearly communicates the scoped side effect, which is exactly the behavioral nuance expected.

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 economical and well-structured: a single opening sentence stating the core action and side effect, followed by a two-sentence usage note. No redundant phrasing; every sentence adds useful 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?

Given the tool's simple scope, the description covers the essential behavior (set level, create if needed), the per-environment preservation, and practical usage with reset_logger. An output schema exists, so return values need no explanation, and the annotation set is sufficient.

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% since all parameters are described. The description enhances parameter meaning with 'dial up verbosity (e.g. DEBUG)' for the level parameter and 'Other environments are preserved' clarifying the environment parameter's scoping, going beyond the schema's baseline.

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-resource pair ('Set a logger's level') and includes the key scope 'in one environment' and side effect 'creates the logger if needed'. It clearly distinguishes from sibling tools like reset_logger and list_loggers by focusing on the mutation 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 explicitly guides when to use the tool: 'dial up verbosity (e.g. DEBUG) to investigate an issue' and names the alternative for reverting: 'then reset_logger to revert'. It also mentions list_environments implicitly for valid targets, giving clear 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?

The description discloses key behavioral aspects beyond annotations: it sends a sample request, returns success status/response parts/latency, and is safe ('Dry-run'). Annotations include readOnlyHint=false (which could imply mutation) but the description explicitly states it is a dry-run and non-destructive, clarifying that no state is saved. It also explains the purpose ('prove the endpoint works') which adds behavioral context. This goes above and beyond what annotations provide, so a 5 is warranted.

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 concise: two sentences plus a return-value list. It front-loads the core action ('Dry-run a forwarder destination') and then adds the key details (what it returns and why to use it) without fluff. Every sentence earns its place, and the structure is tight and scannable.

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 high complexity (8 params, output schema, sibling operations), yet the description covers the core purpose, usage context, return values, and clarifies safety (dry-run). The output schema details the response structure, so the description doesn't need to explicitly list return fields, but it does summarize what's returned. The description is complete for an agent to decide when to invoke and what to expect.

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 already explains every parameter. The description adds value by explaining the overall semantics of the tool (sending a sample request and returning diagnostics), but does not repeat parameter details. Since coverage is complete and the description reinforces the purpose, a baseline 3 is exceeded slightly because the description provides a mental model of how the parameters fit together (e.g., 'sample request' implies the url/body/method are used together). However, it doesn't add per-parameter nuance, so 4 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?

The description uses a specific verb ('Dry-run a forwarder destination'), names the resource ('destination'), and clearly distinguishes from siblings by explaining its purpose: 'prove a SIEM endpoint works before wiring create_forwarder'. It also mentions the exact actions and return values, making it unambiguous.

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 explicitly states when to use this tool: 'Dry-run a forwarder destination before saving it' and 'prove a SIEM endpoint works before wiring create_forwarder'. It not only gives the context but also names the alternative (create_forwarder) and positions this as a pre-check, effectively saying 'use this instead of directly creating'. This is a clear when-to-use statement.

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?

It discloses the read-modify-write behavior ('reads the current job, applies your change, and saves the full updated job'), which is valuable beyond the destructiveHint annotation. This explains why partial changes work correctly, adding meaningful 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 two short sentences, front-loaded with the primary action, and every word earns its place. The second sentence explains the partial-update mechanism using a concrete example, making it both concise and instructive.

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 a rich 14-parameter schema, output schema, and a clear explanation of partial-update semantics, the description covers the core interaction. It does not fully anticipate edge cases like clearing fields with null, but the schema descriptions and annotations fill most 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?

Schema coverage is 100% with descriptive parameter text, so the baseline is 3. The description adds important parameter semantics by emphasizing that only changed fields need to be passed, and the example 'move it to 8am' illustrates how run_at can be used without touching other fields.

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 'Change a job' — a specific verb and resource that clearly distinguishes this from siblings like create_job, delete_job, and run_job. It also clarifies the scope (an existing job) without ambiguity.

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 instruction 'Only pass the fields you want to change' provides clear usage context for partial updates. While it does not explicitly name alternatives or exclusions, the wording implies this is the tool for modifying existing jobs, which is sufficient given the sibling set.

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