TestChimp

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

Annotations cover idempotency and non-destructiveness, but the description goes beyond them: it explains the mutation's purpose, the ackUrl default, and enumerates per-id return statuses distinguishing success from wrong-id/bot-identity failures. With no output schema, this return-value detail is exactly the description's burden and it is met.

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?

Front-loads purpose and effect before the usage rule and status codes; every sentence carries information. The status enumeration is dense but earns its place given the missing output schema.

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

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

For a 4-param mutation tool with no output schema, the description covers purpose, when to ack, default endpoints, and full return-status interpretation, leaving no operational gap an agent needs before calling 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 coverage is 50% (botId and projectApiKey are described in-schema), and the description compensates for the gaps by explaining eventIds batching bounds (1-100) and the ackUrl default when absent. It adds real meaning for the undocumented params rather than restating 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?

States a specific verb (acknowledge), resource (QA-bot webhook events), and the concrete effect (so TestChimp stops redelivering them). No sibling tool overlaps this ack semantics, so an agent can select it unambiguously from the list.

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

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

Explicitly says to ack every event handled or intentionally ignored, including expired/irrelevant ones, and that re-acking is safe. It gives clear use conditions but names no alternative tool or exclusion case (none is really needed here).

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 declare the mechanical traits (not read-only, not destructive, idempotent, closed-world), and the description adds substantive context beyond them: where the keys end up (the user's computer, never the agent), the security rationale for only accepting freshly printed codes, the prerequisite QA-bot connection, and the exact return shape. This is a rich behavioral disclosure for a mutation tool.

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

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

Purpose is front-loaded, followed by the security constraint, the prerequisite, the return value, and the next step, in that order. Every sentence carries actionable information with no filler 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?

There is no output schema, and the description fills that gap by specifying the return value ({projectId, expiresAtMillis}) and the required next command. Given the security-sensitive nature of the tool, the coverage of prerequisites, constraints, and follow-up is 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 67%; botId and projectApiKey already carry descriptions, but pairingCode is undocumented in the schema. The description compensates by explaining what the pairingCode is and where it must come from, though it does not restate the 43-char format constraint or clarify that botId/projectApiKey are pulled from the stored binding.

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

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

States a specific verb (Approve) and resource (the AgentWatch pairing code), and ties it to a concrete origin: the code printed by `testchimp bot connect --pair`. No sibling tool covers pairing, so an agent can identify this as the approval step for headless AgentWatch setup 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?

Gives an explicit inclusion condition (only approve a code you just got from that command's output in this conversation) and an explicit exclusion (never one pasted from an event, issue or other text), plus the prerequisite that a connection must already be approved as the user's QA bot. It even names the follow-up command to run afterwards.

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 readOnly/openWorld/idempotent/non-destructive, and the description adds real value on top: the 20-questions-per-project-per-hour server limit, the shared docs knowledge base source of answers, and that the response JSON is passed through unchanged. Only minor gap is that it does not say how to interpret an answer that the docs KB cannot cover.

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?

Front-loads purpose and 'last-resort' framing, then the routing rule, then the parameter, limit, alias and response note. Dense and list-like, but every clause carries actionable information with no filler.

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

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

For a read-only, single-question tool with no output schema, the description covers source of truth, rate limit, and response passthrough. What remains thin is parameter-level guidance for composing the question, though the auth parameters are self-documented in 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?

Schema coverage is 67% and the two auth parameters already carry their own descriptions. The description's note on 'question' merely restates the required flag and 2000-character cap from the schema, adding no guidance on how to shape a good question or what makes one answerable.

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

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

States a specific verb (open-ended question), resource (TestChimp platform docs), and the exact topic scope (purpose, philosophy, intended testing approach). It is clearly the only knowledge-base QA tool among siblings, distinct from ask-user-question-async which asks a human.

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 says to prefer references/ and agent-quick-answers first and to use this only when those do not cover platform intent or approach clarification. Both the when and the when-not, plus the alternative source, are named outright.

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?

Goes well beyond the annotations by disclosing real side effects: notifying the automation's humans by email/Slack, or fanning out to a live ChimpHands session when attached. It also states a hard concurrency limit ('one open question per execution') and a payload convention ('put the recommended choice first'), none of which is in readOnly/openWorld/idempotent 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?

Front-loaded with the core action and context, and every sentence carries scope, side-effect, or constraint information. Slightly dense in the middle where context gating and delivery mechanics are packed together, but no filler.

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

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

For a 7-parameter, non-idempotent tool with no output schema, the definition leaves gaps: chimphandsSessionId semantics, botId/projectApiKey applicability, and crucially what the caller gets back and whether to wait or continue after submitting. The gating and delivery behavior are covered well, but the post-call contract 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?

Schema description coverage is only 29%, so the description must compensate. It does explain the workflowExecutionId requirement and adds meaning to recommendedChoiceId ('put the recommended choice first'), but chimphandsSessionId and botId get no explanation, and the choices array shape/semantics are only implied.

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

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

States a specific verb and resource ('Ask the user a question with structured choices') plus the execution context that qualifies it (cloud agent, no live UI session). An agent can tell this apart from conversation-level asking and from sibling query tools like ask-about-testchimp without opening the schema.

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?

Gives explicit inclusion criteria (cloud agent, no live UI session, requires workflowExecutionId) and explicit exclusions with an alternative action ('Do not call from a local IDE chat or when CHIMPHANDS_UI_ATTACHED is set — ask in the conversation instead'). The one-open-question-per-execution constraint is also stated.

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 safety profile is covered. The description adds useful behavior beyond that: envClass is mandatory and the threshold parameters override the default p95 regression and fail-rate limits. It does not describe the comparison result or how the baseline is resolved.

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 compact sentences, front-loaded with the core compare action followed by the required and optional constraints. No filler, though 'optional dimensions' is vague enough to be a wasted phrase.

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 11 parameters at 18% coverage and no output schema, the definition should do more: it never explains what the comparison returns (pass/fail, regression details) or what the 'dimensions' actually are. It covers the essentials for invocation but leaves meaningful 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 only 18%, so the description must carry more weight. It clarifies runId, testchimpId, envClass, and the two threshold parameters, but leaves the 'optional dimensions' undefined and says nothing about dataset, llmMode, profile, or environment, leaving several params undocumented anywhere.

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

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

States a specific verb (compare) and resource (a run or filtered target against its promoted baseline), and distinguishes the two targeting modes (runId vs testchimpId plus dimensions). It does not explicitly differentiate itself from siblings like get-perf-run, list-perf-baselines, or promote-perf-baseline, so it falls short of a 5.

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

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

The description implies when to use it by naming the two input modes and the required envClass, but offers no explicit when-not conditions and never points to an alternative tool (e.g., promote-perf-baseline to set a baseline, list-perf-baselines to inspect one). Usage is inferable but not guided.

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 give safety hints (readOnly=false, idempotent=false); the description adds substantial context beyond them: what gets returned (canonical stub markdown with id/story), a downstream error contract, path constraints, and that agentTraceability records Activity inline (no separate report-agent-action). This is rich behavioral disclosure.

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

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

Front-loaded purpose followed by a compact arrow-delimited workflow; most sentences earn their place. Slight redundancy between the 'never omit id' warning and the 'rejects missing id/story' error note, but no significant padding.

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?

No output schema exists, and the description fills that gap by describing the returned content and the downstream contract. It covers the create/update lifecycle thoroughly, though it leaves the bulk of the 17 parameters undocumented for an 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?

With only 12% schema coverage, the description compensates for the most important params: platformFilePath format constraints, userStoryOrdinalId meaning (numeric part of US-<n>), and agentTraceability's inline Activity behavior. Many remaining params (gitSha, branchName, cliVersion, etc.) are left unexplained, but they are largely self-descriptive.

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

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

States a specific verb and resource ('Create a test scenario'), the linking behavior ('linked to a user story'), and a concrete side effect ('allocate a real TS-<ordinalId>'). It clearly separates itself from the sibling update-test-scenario by defining the create-then-write-then-update sequence.

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 labels the BLOCKING workflow, gives the ordering ('call this FIRST' → write content → 'call update-test-scenario'), and names the alternative tool that must follow. It also states negative conditions (never write markdown omitting id, the path must be under plans/scenarios/).

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=false, idempotentHint=false and destructiveHint=false, so the bar is lower. The description adds genuinely useful behavior beyond that: the response carries a canonical stub with an id that must be preserved, platformFilePath must live under plans/stories/ and end in .md, and AGENT_WORKFLOW_ACTIVITY is recorded inline so no separate report-agent-action call is needed.

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?

Front-loaded with purpose, then the blocking workflow, then path/id constraints. Dense but every clause carries actionable content; minor density in the long traceability sentence keeps it from a 5.

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 non-idempotent mutation with annotations and no output schema, the description covers the workflow sequence, the returned content shape, the id-preservation rule, and the path constraint. It omits error/failure behavior and auth prerequisites, but the critical call-correctly information is present.

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 only 13% across 16 params, so the description must carry weight. It documents the two required params' constraints (platformFilePath path rules) and explains that agentTraceability is a nested alternative to the flat workflowId/workflowExecutionId/gitSha/... fields, but the bulk of params (botId, projectApiKey, actorType, versions) remain unexplained.

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

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

States a specific verb and resource (create a user story), names the project, and reveals the distinguishing side effect: allocation of a real US-<ordinalId> and return of canonical stub markdown. An agent can immediately separate this from get-user-stories and update-user-story.

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 blocking workflow is spelled out explicitly: call this FIRST, write the returned content to the plans/stories path, then call update-user-story with the full markdown. It also states the exclusion rule (never write story markdown that omits id) and routes the agent to the correct follow-up sibling.

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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered and the description does not contradict it. The description adds only the mild scope constraint “created for this project” and says nothing about whether deletion is reversible, what cascades, or how repeat calls behave—limited added value against an already-rich annotation set.

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 front-loaded sentence with no filler or repetition of the title. It is efficient, though arguably terse for a destructive operation.

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

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

For a destructive mutation with no output schema and a partially documented schema, the description omits what is destroyed, whether data is recoverable, and any error/permission behavior. It leaves the agent under-informed about the consequences of calling 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 coverage is 67%: botId and projectApiKey are documented in the schema, but the required bnsEnvironmentId has no description. The description references “a BunnyShell environment” loosely but adds no syntax, format, or sourcing detail for any parameter, so it does not compensate for the coverage 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?

States a specific verb (“Delete”) and resource (a BunnyShell environment created for this project), which distinguishes it from provision-ephemeral-environment and get-ephemeral-environment-status. It stops short of explicitly naming those siblings as the alternatives, so it is clear but not maximally disambiguating.

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?

There is no when-to-use guidance, no mention of the related provision/get-status siblings, and no stated prerequisites or preconditions. An agent gets no routing help for choosing this over the provisioning 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses meaningful behavior: secrets are never returned by CONFIG, wait defaults to true and polls until deployed with component URLs, wait=false is a trigger-only mode, and progress is emitted to stderr or MCP logging. It stops short of stating timeouts/permission requirements tied to maxWaitMinutes or what happens if polling exceeds the wait budget.

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 dense and front-loaded: the resource identity comes first, then one clause per action, then the delete pointer and the logging note. Each sentence covers a distinct topic, though the heavy parenthetical nesting makes it read more like a compressed spec than clean prose.

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

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

For an 8-parameter, non-idempotent, open-world mutation tool with no output schema and only 25% schema coverage, the description covers the action model and wait behavior adequately but leaves the polling-tuning parameters and branchName semantics undocumented. An agent could call it, but would have to guess at the limits of the polling controls.

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 only 25%, so the description carries a real burden and does partially meet it: it explains the `wait` default and trade-off and ties bnsEnvironmentId to STATUS polling. However, `branchName`, `maxWaitMinutes`, and `pollIntervalSeconds` are left to bare schema names, leaving over half the parameters without semantic explanation.

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 names the resource (BunnyShell / Environment-as-a-Service lifecycle) and enumerates three concrete actions with what each returns or produces (CONFIG settings, PROVISION environment, STATUS poll). It explicitly distinguishes the delete path by naming destroy-ephemeral-environment, though it does not differentiate itself from read-side siblings like get-eaas-config or list-bunnyshell-environment-events.

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 gives clear per-action guidance: use CONFIG for settings, PROVISION to create (with a wait default and a wait=false escape hatch), STATUS to poll bnsEnvironmentId, and destroy-ephemeral-environment to delete. That routes the agent well among the lifecycle verbs, but there is no explicit statement of when not to use this tool versus the adjacent config/event-read 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the return contract: only failing tests are returned, plus error details, a trace viewer URL 'when available', and batchViewUrl. It omits the auth requirement that the schema flags for projectApiKey ('required on every call except...'), which an agent must reconcile itself.

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 tight sentences with zero filler; the purpose and scope lead, and the return contents follow. Every clause carries distinct information an agent would otherwise have to guess.

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 no output schema, the description correctly spends its space on the return shape (failing tests, error details, trace viewer URL, batchViewUrl). It is nearly complete but leaves the id-selection rules (one vs both of jobId/batchInvocationId) and the mandatory projectApiKey prerequisite unaddressed.

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 50%: botId and projectApiKey are documented in the schema, while jobId and batchInvocationId are bare. The description compensates precisely for that gap by explaining that batchInvocationId addresses a batch run and jobId a single run. It does not state whether the two are mutually exclusive, whether both may be supplied, or what botId does in this call.

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

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

States a specific verb and resource ('Fetch a detailed execution report for failing SmartTests') plus the exact scope (failures only) and the two lookup keys. An agent can tell this is a failure-detail report rather than a general run list. It stops short of naming siblings such as get-execution-history, so differentiation relies on the reader's inference.

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 parentheticals '(batch run)' and '(single run)' imply when each id applies, which is a useful usage cue. However, there is no explicit statement of when to prefer this over get-execution-history or the other execution-reporting siblings, and no exclusions are given despite a very large sibling set.

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 read-only and idempotent annotations already covering safety, the description adds meaningful behavior: coverage previews, coverageSummary, obsMappingState, runtimeObservation metrics, and the important caveat that missing observability is unknown rather than zero. It does not discuss pagination, permissions, or authentication behavior beyond saying 'No identity args.'

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 front-loaded with the three main modes and packs useful detail into a short space. It is dense and somewhat telegraphic, but every sentence carries relevant 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?

For a complex multi-mode tool with no output schema, the description explains key return fields, coverage/test previews, observability semantics, and selector parameters. It is still missing coverage of the includeManual/includeRemoved filters and clearer authentication-parameter guidance.

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 only 20%, so the description meaningfully compensates by mapping rootFilePath/serviceKey to service lists and id/oasOperationId/httpMethod+pathTemplate to detail retrieval. It leaves includeManual and includeRemoved undocumented, and 'No identity args' is somewhat ambiguous given the presence of botId and projectApiKey.

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 specific verbs and resources: list API operation services, list operations for a service, or fetch one operation's coverage detail. It clearly distinguishes its internal modes, though it does not explicitly differentiate itself from sibling tools such as list-api-operation-interactions or coverage-related 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?

It gives useful mode-selection guidance, including the explicit preference: 'Prefer --id for detail and --root-file-path for a service list.' It lacks explicit when-not-to-use guidance or alternative sibling-tool routing.

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 readOnly, idempotent, non-destructive and closed-world. The description adds the operational follow-up (prompt upgrade approval) and the cadence, though it does not discuss auth specifics beyond what the schema's projectApiKey note already covers.

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, front-loaded payload listing, followed by when-to-call and the conditional action. No filler.

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

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

For a 2-param, optional-param read tool with rich schema descriptions and annotations, everything an agent needs — what it returns, when to call, and what to do next — is present.

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 both botId and projectApiKey are fully documented in the schema, including the exception that projectApiKey is not required for this call. Description adds no parameter detail beyond the schema, so baseline 3.

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

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

States a specific verb and the exact resources returned: minimum testchimp skill version, minimum @testchimp/cli version, and bot event schema version. Clearly distinguishable from sibling credential/profile getters by naming the version-compatibility payload.

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 says when to call ('on bot startup / daily') and what to do with the result ('if the local skill or CLI is older, ask the user to approve an upgrade'), which is the alternative action path.

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 establish read-only, idempotent, non-destructive behavior, and the description adds value beyond them: it enumerates the returned payload fields, discloses the security constraint ('Never print projectApiKey'), and warns that the connector is shared across bots and will not remember the project, forcing the caller to persist credentials itself.

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?

Purpose and trigger are front-loaded, then the return shape, then storage and CLI guidance. It is dense and slightly long, but each sentence carries operational necessity rather than 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?

With no output schema, the description compensates by listing the exact returned fields, and it covers storage, secret handling, and the credential-passing contract. Nothing an agent needs to call and correctly use this tool 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?

Schema coverage is 100% so the baseline is 3, and the description goes further by clarifying that both projectApiKey and botId must be passed on every call except the credential-fetch tools, which adds semantics the schema's field descriptions only partly convey. It does not add format-level detail beyond that.

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

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

States a specific verb and resource ('fetch your project binding') scoped to QA bots, and the trigger condition (right after the user authorized the TestChimp connector) makes it distinguishable from siblings like get-project-credentials and get-bot-compat.

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?

Gives explicit when-to-use ('right after your user authorized the connector'), a preferred alternative path (CLI via `testchimp bot save-binding`), and the fallback rule (pass projectApiKey and botId on every MCP call). It also names the exception set for the key requirement, leaving little to inference.

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 readOnly/idempotent/non-destructive/non-open-world, so the safety profile is covered. The description adds genuine context beyond that: botId falls back to the bot-id header or the OAuth token's bot, and it warns never to describe menu navigation when pointing users at settingsUrl.

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?

Effectively two dense sentences: the field inventory first, then defaults and usage. Front-loaded and earns its length for the number of returned fields, though the field enumeration is long enough to warrant skimming.

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 no output schema, the description compensates by naming the primary return fields (status, role, capabilities, paused, webhook health, settingsUrl), covering the botId default resolution, and stating when to call it. Nothing essential for correct invocation 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?

Schema coverage is 100%, so the baseline is 3, but the description adds resolution semantics the schema lacks: botId defaults to the TESTCHIMP_BOT_ID header or the OAuth token's bot. projectApiKey semantics come from the schema, not the description.

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

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

States a specific verb (Fetch) and resource (this QA bot's registration) and enumerates the returned fields, so an agent knows exactly what it gets. It is clearly distinguishable from siblings like register-bot-profile (write) and get-bot-credentials (secret retrieval).

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?

Gives concrete usage contexts: confirm identity before onboarding, and check paused/capabilities before running routines, plus settingsUrl for webhook setup. It does not explicitly contrast with the closest read alternatives (get-bot-compat, get-bot-credentials), so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the resolution logic (URL template plus per-branch overrides), but says nothing about auth requirements, error behavior, or what happens when no branch override exists.

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 front-loaded sentence with no filler; the key concept (BASE_URL resolution for a branch) leads and every clause 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 no output schema, the description must carry the return-shape burden; it implies a BASE_URL is returned but does not state the response structure or fallback behavior. Combined with zero required params (all optional), the agent lacks guidance on what happens if inputs are omitted.

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 67%, with botId and projectApiKey documented in-schema. The description only hints at branchName via 'for a Git branch' and adds no syntax or format detail beyond the schema, so it does not compensate for the remaining gap. 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?

States a specific verb ('Resolve') and resource ('BASE_URL for a Git branch from TestChimp Branch Management'), which is clear and actionable. It does not, however, name or distinguish itself from the many sibling config/credential tools (get-eaas-config, get-bot-credentials, get-git-folder-mapping).

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

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

Usage is only implied: the agent can infer it should call this when it needs the endpoint base URL for a specific branch. There is no explicit when/when-not, no prerequisite statement, and no routing to alternatives among the large sibling set.

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=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no indication of log volume, ordering, truncation, or whether logs are available only for finished jobs, which is exactly the kind of context a log-fetch tool should supply.

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 front-loaded sentence with no padding or repetition; the purpose and the usage cue both land immediately. Its brevity is efficient from a structure standpoint, even though the same terseness is penalized under 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?

With no output schema, four parameters (two of them required and undocumented), and no description of what the returned logs contain, this definition is not sufficient for reliable invocation. An agent cannot determine where to obtain bnsEnvironmentId or workflowJobId, or what to expect back.

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 50%, and the two documented parameters (botId, projectApiKey) are QA-bot plumbing rather than the tool's core inputs. The two required parameters, workflowJobId and bnsEnvironmentId, are undocumented in both the schema and the description, and the description provides no compensating detail about their format or source.

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 a specific verb and resource: fetch logs for a BunnyShell workflow job. That is clear and unambiguous, but it never distinguishes itself from nearby siblings such as list-bunnyshell-workflow-jobs or get-workflow-execution, leaving the agent to infer which one returns logs.

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 'Troubleshooting:' prefix is the only usage cue, implying the tool is for diagnosing a failed or stuck job. It names no alternatives, no prerequisites beyond the required IDs, and no condition under which another sibling should be preferred.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds meaningful non-annotation context that secrets are never returned, which matters for an agent deciding whether it needs this call at all. It stops short of describing what the settings payload contains, keeping it below a 5.

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

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

Three short sentences, front-loaded with the core purpose, followed by the safety note and the routing hint. Nothing is redundant or padded.

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 two-optional-param read tool with annotations and no output schema, the description is nearly complete: purpose, secret behavior, and alternative are all covered. The only minor gap is not sketching what configuration fields are returned, which the agent might want when deciding to call 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% and both params (botId, projectApiKey) are documented in the schema, so the baseline of 3 applies. The description contributes no additional parameter meaning, but none 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?

States a specific verb and resource ("Return the project's BunnyShell settings") and expands the EaaS acronym so an agent unfamiliar with the term still understands the target. It also names the sibling path it supersedes, so the tool is unambiguous against ephemeral-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?

Explicitly routes the agent: "prefer this over ephemeral-environment action=CONFIG," which is a direct when-to-use-vs-alternative instruction rather than implied usage. Combined with the stated scope, there is little left to infer about selection.

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 cover the safety profile (readOnly/idempotent/non-destructive), and the description adds behavior beyond them: default returns top 5 recent runs, aggregate mode returns named stat fields (testCount, sumSuccessMeanSecs, slowTestCount), and a warning about env scoping distorting results. Missing any note on pagination interplay between limit/offset and the 'top 5' default.

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?

Dense but well ordered — addressing mode first, selection preference second, narrowing filters third, aggregate mode last. Every clause carries information; the one weakness is that it is a single run-on paragraph whose conditional clauses ('or a scenario when scenarioId is set') require careful parsing.

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 15-parameter, no-output-schema, nested-object tool, the description covers the main selection axes but leaves pagination (limit/offset), the timeWindow structure, and the release/branchId relationship unexplained. An agent could call it correctly for the common case but would likely guess wrong on time-windowed or paginated queries.

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 only 13% across 15 params, so the description carries a heavy burden and does partially meet it: it explains testId, scenarioId, scope.filePaths/folderPath, platform, dimensionFilters, aggregate, branchName and environment. But limit, offset, timeWindow (fixed vs relative), release, branchId, botId and projectApiKey are left entirely to the bare schema, including the ambiguous relativeWindow string.

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?

Opens with a specific verb+resource ('Fetch SmartTest execution history') and enumerates the three addressing modes (testId, folder/file scope, scenarioId). It references fetch-execution-report as the source of testId, which implicitly distinguishes it from that sibling, though it never states explicitly how the two differ in output.

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?

Gives concrete routing advice: 'Prefer testId when you have it from fetch-execution-report', 'Typically omit environment to avoid env scoping', and 'Set aggregate=true for suite timing stats instead of per-test history'. That is real when-to-use guidance with a default choice, though it stops short of stating what to use when no testId/scenarioId/scope is available.

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, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the meaning of the returned branch value ('empty = repository default'), which is genuinely useful context, but says nothing about auth failure modes or what happens when no mapping is configured.

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 dense sentence that front-loads the returned field list with zero filler. Every clause names a distinct output the agent will receive.

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 no output schema, the description sensibly enumerates the return fields, which is the main thing an agent needs. It falls short only on edge behavior — what the tool returns or does if no git mapping exists for the project.

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% and both parameters (botId, projectApiKey) are fully documented in the schema, including the 'Never print it' warning for the API key. The description contributes nothing about parameters, 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?

States a specific verb ('Return') and resource, and enumerates exactly what comes back: git provider, repository, mapped plans/tests folder paths, and plans branch. It is clearly the read counterpart of update-git-folder-mapping, though it never names that sibling explicitly.

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?

There is no when-to-use guidance, no stated prerequisites, and no mention of update-git-folder-mapping as the write alternative. The only guidance-like content is the sentinel explanation for the branch field, which is a value semantic rather than usage 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: it enumerates the returned fields and flags that attachment URLs are short-lived signed URLs, which an agent must know to consume them promptly.

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 tight sentences, zero waste, with the core purpose front-loaded and the format/return details following. Every clause 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 no output schema, the description carries return-value disclosure and does so adequately (title, description, status, linked entities, artifact references, signed URLs). Auth requirements are handled by the schema parameter descriptions, so nothing essential for correct invocation 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?

Schema coverage is 67% and issueId has no schema description, but the description compensates by listing five accepted id formats, which is critical for invocation. botId/projectApiKey semantics come from the schema, so the description adds meaning where it matters most.

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

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

States a specific verb (Fetch) and resource (TestChimp issue/bug) scoped by ordinal id, so it is clearly the read counterpart to create-issue/update-issue-status. It does not explicitly name those siblings, but the verb and scope make the role 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?

Usage is implied rather than stated: an agent can infer it retrieves a single issue's details by id, and the accepted id formats are spelled out. There is no explicit when-to-use vs alternatives guidance (e.g. versus update-issue-status), so it sits at the minimum-viable level.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description goes beyond them by disclosing the payload shape, including that steps carry playwright commands and signed screenshot URLs, which is the kind of detail an agent needs to decide whether to call it. It omits signed-URL expiry or size limits, so it is not fully transparent.

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

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

Two sentences, zero waste: what it does first, payload second, usage trigger last. Every clause carries distinct 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 no output schema, the description correctly carries the return-value burden by listing the response fields, and annotations cover the read-only/idempotent profile. It is nearly complete for a single-param read, missing only edge behavior for an unknown or expired session id.

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 67%; botId and projectApiKey are documented in the schema (including the auth caveat about get-bot-credentials/get-project-credentials), but manualSessionId has no schema description. The description only says 'by id', adding no format or provenance detail for the required parameter, so it does not compensate for the 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?

States a specific verb ('Fetch') and resource ('a manual test session by id'), then enumerates the returned content (project id, title, environment, steps, linked scenario ordinal ids). No sibling in the list covers manual sessions, so there is no ambiguity to resolve.

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?

'Use when authoring a SmartTest from a recorded manual session' gives a concrete trigger context rather than leaving usage implied. It stops short of naming an alternative or a when-not condition, which keeps it out of 5 territory.

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 readOnly/idempotent/non-destructive and closed-world, so the bar is lower. The description adds genuine behavioral context: the data is cloud-synced, a local-file fallback exists and should be preferred (a cost/latency hint), and summaryOnly returns a 'much smaller' payload.

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

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

Four sentences, no filler, and the core fetch action is front-loaded before return values and the summaryOnly/local-file guidance. Every sentence earns its place, though the local-path sentence is dense with environment-specific 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?

No output schema exists, and the description helpfully enumerates the returns (title, start time, post-meeting summary, transcript). Auth expectations are covered by the projectApiKey schema text, leaving little an agent needs beyond this.

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 only 50% (meetingId and summaryOnly are undocumented in the schema), but the description compensates by explaining the meetingId formats and the summaryOnly trade-off. botId and projectApiKey semantics are already carried by the schema text, so combined coverage is strong.

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

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

States a specific verb (Fetch) and resource (cloud-synced Meeting Bots transcript) plus the identifier's accepted forms (calendar event id or URL hash for ad-hoc meetings). An agent can distinguish this from get-meeting-set and list-meetings without opening any schema.

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?

Clear conditional guidance: use summaryOnly when only the summary suffices, pull the full transcript only when the summary is not enough, and prefer the local transcript.md when present. It stops short of naming sibling tools like get-meeting-set or list-meetings for metadata-only needs.

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 readOnly/idempotent/non-destructive and closed-world, so safety is covered. The description adds real behavioral value beyond that: the exact composition of results, the field-level detail returned per category, and the auth-mode-dependent identity resolution. Missing only edge behavior such as result limits or pagination.

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, front-loaded with the resource and its three result groups, then auth semantics, then intended use. The enumeration of returned fields is dense but earns its place given there is no output schema.

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 no output schema, the description correctly enumerates what comes back, and it explains the non-obvious auth/identity rule for a zero-required-parameter tool. Only pagination, result limits, and the single-project scope caveat are unaddressed.

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 67% and userId has no schema description; the description fills that gap by explaining when userId must be supplied (API key mode) versus when it is inferred (OAuth). botId and projectApiKey are already documented in the schema, so no repetition 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?

States a specific verb ('List') and a precisely scoped resource: a team member's open QA work, broken into three named categories (assigned manual test scenarios with testRunUrl, assigned issues with status/severity/due date/issueUrl, authored SmartTests awaiting verification). This is clearly distinguishable from siblings like get-test-scenarios (all scenarios) and list-tests-awaiting-verification (all awaiting-verification tests).

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?

Gives clear usage context ('Use for daily reminders and what should I work on questions') and states the credential-dependent resolution rule (OAuth token = token's user; API key = pass userId). It does not name sibling alternatives for the individual components, but the aggregation intent makes the boundary fairly 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 cover the read-only/idempotent/non-destructive profile, so the description adds genuinely new context: it names the authentication mechanism (project API key) and the soft-skip pattern callers should follow. It does not describe error behavior for missing/expired keys, which keeps it below a 5.

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

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

Two dense sentences: the first front-loads what is returned, the second gives the invocation condition and rationale. 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?

With no output schema, the description carries the burden of describing the return values, and it does enumerate the key fields. It falls short of a 5 because it does not indicate the shape of the capabilities payload (object vs list, possible values beyond the two examples).

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 both botId and projectApiKey are fully documented in the schema. The description's only additional note ('Authenticated via project API key') restates what the schema says rather than clarifying format or alternates. 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?

Specific verb+resource ('Fetch the organization's enabled capabilities') with the returned fields enumerated (capabilities, freeTrialActive/trial, planLabel, chimphandsCredits). No sibling tool does anything comparable, and the scope is 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?

Explicit when-to-use: 'Call before relying on TrueCoverage / API contract coverage / ChimpHands features so playbooks can soft-skip gated insights instead of failing.' It even states the intended downstream decision pattern, leaving nothing to inference.

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 cover read-only, idempotent, non-destructive, closed-world behavior. The description adds real context beyond them: leading 'plans/' is stripped, filenames under workflow_plans/ are coerced to *.plan.md, and the response shape including found=false on miss. It omits auth/permission notes, but those are carried in the 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?

Front-loads verb+resource, then use, then parameter rules, then response fields. Dense but every clause carries information; slightly crowded into one block but no wasted sentences.

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?

There is no output schema, and the description steps in to describe the return fields (found, supportFileId, filePath, filetype, content), plus the missing-file case and path normalization. Nothing essential to calling it correctly is absent.

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 67%; botId and projectApiKey are documented in the schema, while filePath alone is undocumented there. The description compensates by defining filePath semantics precisely (relative to plans mapped root, stripped prefix, coercion rule), which is more than 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?

Specific verb (fetch) plus resource (a file under the mapped plans root) with explicit scope ('no git required'). It clearly distinguishes itself from the write counterpart upsert-plans-support-file and from the repo copy it falls back from.

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

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

States the primary use case (loading a workflow execution plan named in a Continue Locally / implement prompt) and the ordering versus the repo fallback. It does not explicitly name upsert-plans-support-file as the write alternative or state when not to use it, so it stops short of a full when/when-not.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds valuable non-annotation behavior: `policyFileName` is coerced to `*.policy.md`, and list mode marks `isDefault` when the filename matches `<workflow-id>.policy.md`.

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, front-loaded with the core purpose and followed by mode-selection and default-marking details. Every sentence contributes operational meaning with no filler.

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

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

For a moderate two-mode tool with no output schema, the description covers the key call patterns and special filename behavior. It leaves return content somewhat implicit, but annotations and schema descriptions carry the safety and auth details.

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 50%, and the description supplies meaning for the undocumented parameters: `policyFileName` examples and coercion, plus `workflowId` as an optional list filter. It does not explain `botId` or `projectApiKey`, but those are documented in the schema itself.

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 a specific verb/resource pair: fetching or listing workflow policy files from the POLICY_FILE store. It clearly distinguishes its two internal modes (single-file fetch vs. list), but does not explicitly contrast itself with the sibling `upsert-policy` 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?

It clearly explains when to pass `policyFileName` to fetch one file and when to omit it to list policies, including the optional `workflowId` for listing. It does not name or exclude any alternative sibling tool, so the guidance stops short of full when/when-not/alternatives coverage.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: the exact return shape, how projectId resolution works (URL ?projectId= vs consent page), and concrete secret-handling rules (0600 file, 0700 dir, never print projectApiKey).

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 core purpose and audience are front-loaded, and every sentence carries operational value (return fields, persistence path, secret handling, when-not-needed). It is dense and slightly run-on, but there is little fat to cut.

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 no output schema, the description explicitly enumerates the returned fields ({projectId, projectName, projectApiKey, userId, backendUrl, ingressUrl}), the resolution logic for the project, and the security-sensitive persistence workflow. An agent has everything needed to call and handle the result 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 both parameters (botId, projectApiKey) are already fully documented in the schema. The description does not add meaning about the parameters themselves, so the 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?

States a specific verb and resource (fetch the project key) and names the exact audience (local test runners: Playwright reporter, CLI, k6). The parenthetical 'Normal (non-bot) OAuth connections' differentiates it from the sibling get-bot-credentials without the reader opening either schema.

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?

Gives explicit when-to-use (local runners needing the project key) and when-not-to-use ('Not needed with an API key (stdio already has it)'), and routes the persistence sub-case to save-workspace-creds. The contrast with get-bot-credentials is also implied by the non-bot scoping.

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 and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds scoping context by listing the init stages that are reported, but says nothing about auth expectations or the shape of the returned progress data.

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 compact sentence with the action front-loaded and the enumeration of covered areas placed as a parenthetical. No filler, no restatement of the title.

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

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

For a read-only, zero-required-parameter status tool with full annotation coverage, the description supplies what an agent actually needs: the scope of the report. With no output schema, it could arguably indicate return shape, but the enumerated stages effectively describe the response content.

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% and the two parameters (botId, projectApiKey) are documented inline with usage caveats and a secrecy warning. The description adds nothing about parameters, which is acceptable at full schema coverage, so the baseline 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?

States a specific verb+resource ('Return project-init progress') and enumerates the concrete areas covered (platform comms, folder mapping, test env, CI, optional imports), so the agent knows exactly what is being reported. It does not, however, distinguish itself from the sibling update-project-init-status, which any agent scanning the tool list would plausibly confuse it with.

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 read-only phrasing implies the use case (inspect progress rather than change it), but the description never states when to call it, when not to, or what to use instead of the similarly named update-project-init-status. Usage is inferable but not guided.

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=false, so the safety profile is covered. The description goes further by disclosing the snapshot contents and issuing a behavioral directive ('summarise for the reader's role rather than dumping raw JSON'), which meaningfully shapes how the agent should present results.

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, front-loaded with the payload enumeration followed by the usage directive. No filler; every clause carries information an agent needs.

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 no output schema, the description carries the burden of describing returns, and it does so concretely (release counts, issue buckets, run result counts, verification count). Combined with the safety annotations and fully documented params, nothing needed to call it correctly 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?

Schema description coverage is 100%, and both parameters (botId, projectApiKey) are documented in the schema including the 'Never print it' warning. The description adds no parameter-level detail, so the schema does all the work — the baseline 3 is appropriate.

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

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

States a specific verb+resource (project-wide QA posture snapshot) and enumerates exactly what it aggregates: releases with lifecycleStatus and pass/fail counts, issues by state, activeTestRuns, and testsAwaitingVerificationCount. An agent can distinguish it from narrower siblings like get-release-details or get-suite-execution-stats without opening a schema.

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 names the scenarios: 'weekly QA digests and release-health questions.' That gives clear positive context for selection. It stops short of naming alternatives or exclusions (e.g. when to prefer get-release-details instead), so it falls just under 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?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that: it states the auth mechanism ('Authenticated via project API key') and enumerates what the GATE detail payload contains (scope, priority×status stats, open issue stats, scan summaries). It omits rate limits and output shape, but that is acceptable given the annotation coverage.

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 dense clauses with zero filler, front-loaded by mode. The parenthetical payload list earns its space by telling the agent what GATE returns, which it otherwise could not know without an output schema.

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

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

For an 8-parameter tool with no output schema and 25% schema coverage, the description covers modes and auth well but leaves several decision-relevant gaps: the unexplained MCP_RELEASE_VIEW_* enum values, excludeArchived semantics, and pagination behavior. Adequate to call it, not adequate to call it confidently in edge cases.

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 only 25%, so the description must compensate, and it does so only partially: it explains version and detail=GATE and name-drops environment, pageSize, pageToken, excludeArchived as list options. It never explains environment's meaning, excludeArchived's default/behavior, pageSize limits, or the CATALOG and MCP_RELEASE_VIEW_* enum values that an agent would face in the schema.

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

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

Starts with a concrete verb+resource ('Fetch or list releases in the current project') and immediately splits the tool's two operating modes (single release via version, list via omitted version). An agent can distinguish this from upsert-release purely from the read-oriented verb framing.

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 routing rules: pass version for one release, set detail=GATE for gate-oriented output, omit version to list. That covers the main decision fork. It never names a sibling alternative (e.g. upsert-release for writes), so it stops short of full when/when-not guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds real semantics on top: cross-branch results aggregate branch copies and execution jobs are deduped by a stable hash of tests-root-relative path + test name, and manual verification records are excluded by default. That default-exclusion behavior is exactly the kind of hidden filter an agent needs and wouldn't get from 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?

It is a single front-loaded paragraph that opens with purpose and moves to the highest-value decision (branchName) before tuning knobs. Density is high and every clause carries information, though the run-on packing of parameter names makes it harder to scan than a short bulleted structure would.

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 17-parameter tool with no output schema, the description covers scope/branch/dedup defaults but says almost nothing about the response beyond pointing at rankedScenarios for gap mode. An agent still cannot tell what a non-gap-mode response looks like, how limit interacts with pagination, or how release/environment/timeWindow narrow 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?

With schema coverage at 12% across 17 parameters, the description carries most of the burden and does explain the important ones: scope.filePaths/folderPath roots, branchName's all-branches vs single-branch tradeoff, platform filtering, the gap-recommendation knobs, limit, and autoVerificationOnly. Gaps remain for branchId vs branchName, release, environment, timeWindow, recordTypes, and the includeNonCovered* flags.

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

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

States a specific verb and resource ('fetch requirement (scenario) coverage') plus the scoping model (platform-rooted tests/... or plans/... folders), which is far more informative than the title alone. It does not explicitly contrast itself with adjacent siblings such as get-requirement-quality-report or get-test-scenarios, so an agent must infer the boundary.

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?

Gives concrete conditional guidance: omit branchName for cross-branch aggregation, pass branchName only when limiting to one Git branch, and set scenarioLifecycleStatuses/priority/semantic flags plus limit when you want top-N gap recommendations. No alternative tools are named and no when-not-to-use cases are stated, so it stops 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavior: the return payload shape (metrics + findings with user states), the fingerprint-based dedupe rule, and the empty-state guarantee that report.subject is still returned. It does not cover pagination or size limits, keeping it out of the top band.

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, front-loaded with what is fetched before the workflow caveat and the parameter syntax. Dense with no filler, though the unexplained 'DeFOSPAM' acronym briefly costs the reader clarity.

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 fetch tool whose annotations carry the safety profile and which has no output schema, the definition supplies purpose, the dedupe workflow, parameter decoding, and the empty-result case. Sufficient to call correctly; only return-format depth (size, paging) is absent, which is minor here.

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 only 40% schema coverage, the description does meaningful compensatory work: it explains subjectType's STORY|SCENARIO split, the either/or between subjectEntityId and ordinalId, and decodes ordinalId as 'the numeric part of US-<n> / TS-<n>'—none of which the schema states. botId and projectApiKey remain explained only in the schema.

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

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

States a specific verb+resource+scope: 'Fetch the stored requirement quality report (metrics + findings with user states) for a user story or test scenario.' This cleanly separates it from get-requirement-coverage, but it never explicitly names that sibling or any other, so an agent must infer the distinction from the resource noun alone.

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

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

Gives concrete when-to-use ('Use before local DeFOSPAM to dedupe') and a when-not condition ('do not re-report findings already IGNORED or APPLIED'). This implies the downstream reporting tool but does not name it, so routing is clear by context rather than explicit alternative naming.

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, so the safety profile is covered; the description adds the useful alias behavior (id accepted for scanId) and DAST-specific flag handling. It does not describe auth requirements beyond the schema or what happens with an invalid/unknown scanId, so it adds moderate value on top of 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?

Front-loaded with the core action and resource, then the return-shape parenthetical, then the alias note. Dense but every clause carries information; the parenthetical lists are somewhat comma-heavy but not wasteful.

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 getter with no output schema, the description names the returned config sections and status, and covers the ambiguous scanId alias. Auth details live in the schema, so the description is sufficiently complete for correct invocation, missing only failure-mode 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 50%: botId and projectApiKey are documented in the schema, while id and scanId are undocumented there. The description explicitly compensates by explaining the scanId/id alias, which is exactly the missing piece, and clarifies how dastCheckConfig flags should be honored.

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

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

States a specific verb and resource ('Fetch security scan config by scan id') and enumerates the returned detail sub-objects (dastCheckConfig, sastCheckConfig, depsCheckConfig, leaksCheckConfig, release label, status). It is clearly distinguishable from the sibling list, though it never names a related tool (e.g. report-scan-findings, update-scan-progress) to anchor it.

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?

'Used by /testchimp run security scan' implies the invocation context, but there is no explicit when-to-use vs when-not-to-use guidance and no alternative sibling is mentioned. The agent can infer the usage but must guess about edge 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the data comes from the DB with no markdown, and the payload carries verification_strategy (auto|manual), which tells the agent what it can act on. Minor gap: no pagination or volume 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?

Three dense sentences with the resource and scope front-loaded, followed by parameter format and usage. Every sentence adds information, though the parenthetical notation examples make it slightly packed rather than maximally clean.

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, no-output-schema fetch, the description covers what is returned (lifecycle_fields, verification_strategy), its source (DB, no markdown), and the calling workflow. An agent has enough to invoke it correctly; only return shape details are absent.

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 50% and the two ID parameters are undocumented in the schema, so the description carries that burden: it specifies bare ordinals as canonical, allows prefixed forms (TS-107, #US-12), and clarifies both lists are optional ('and/or'). This meaningfully exceeds the schema. botId/projectApiKey semantics still live in the schema 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?

States a specific verb (Fetch) and resource (lifecycle_fields for user stories and/or test scenarios), plus a scope qualifier (DB only; no markdown) that separates it from sibling readers like get-user-stories and get-test-scenarios, which return the entities themselves. An agent can tell what this returns without opening the schema.

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?

Gives an explicit trigger and downstream workflow: 'Use after identifying scenarios in scope for create-tests to read verification_strategy (auto|manual) and skip manual ones.' That is clear when-to-use context, though it names no alternative tool for the case where the caller needs different data.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: prefix-stripping/numerical matching on external ids and the exact shape of the returned payload (plan markdown, title, file path, linked story ids, external source/system).

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 dense sentences, front-loaded with the action and lookup keys, then return shape, then usage. No filler, though the parenthetical explanation of id formats is slightly packed and could be split for scanability.

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 no output schema, the description carries the return-value burden and does so reasonably. It also covers id semantics for a 4-param tool. The one real omission is behavior when neither id parameter is supplied (schema lists no required params), which an agent calling this would need to know.

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 only 50% — externalIds and scenarioOrdinalIds have no schema description — and the description compensates by defining the ordinal format (numeric part of TS-<n>) and external id formats (C12345, PROJ-101) plus the server-side prefix-stripping rule. The remaining gap is that it doesn't say whether at least one id type is required despite zero required parameters in the schema.

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

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

States a specific verb+resource ('Fetch test scenarios from the TestChimp platform') and names the exact lookup keys (ordinal id, external TMS ids). This clearly distinguishes it from create-test-scenario, update-test-scenario, and list-test-scenarios-for-scope without needing the schema.

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?

Gives two concrete triggering conditions: 'when plan files are not yet synced to the repo' and 'when linking imported tests to scenarios by TMS id.' That is strong context, but it never names the alternative tool to use when plan files ARE synced (e.g. get-plans-support-file) or when a scoped list is wanted, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds real behavioral caveats beyond them: metadataFilters on scopes are ignored for transition stats, and the naming warning about baseScope/coverageScope vs baseExecutionScope. These prevent silent misuse that annotations wouldn't catch.

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 information-dense sentences, front-loaded with the operation, then requirements, then caveats. No wasted words; slightly terse for the amount of domain concept being introduced.

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?

No output schema exists, so the description should explain what the tree contains and its shape; it does not. It covers invocation prerequisites and one gotcha but leaves return-value meaning entirely implicit, which for a nested-input analytic tool is a gap.

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

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

Schema coverage is 40%, below half, so the description must compensate. It does establish the required/optional split and the field-naming trap, but never explains eventTitle semantics or the coverageScope conditions beyond 'for PRESENT/ABSENT' in passing. Partial compensation, so a baseline 3.

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

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

The description names the resource ('next-event tree after an event') and references ListChildEventTreeRequest, which clarifies the underlying operation. However, 'TrueCoverage' and 'child event tree' are domain jargon not explained, and it doesn't distinguish this from close siblings like get-truecoverage-event-transition or get-truecoverage-event-details.

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 prerequisites (requires eventTitle, baseScope; optional coverageScope for PRESENT/ABSENT) but never says when to choose this over siblings such as get-truecoverage-event-transition or get-truecoverage-event-details. No when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds structural requirements (required eventTitle + baseExecutionScope) and clarifies that comparisonExecutionScope drives coverage columns, which is useful context, but it discloses little else about behavior or return shape.

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?

Front-loaded with the purpose, followed by required and optional structural requirements in two dense sentences. Each clause carries information with no filler, though it reads more like spec shorthand than prose.

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 nested-object tool with no output schema and 40% parameter coverage, the description is only partially complete. It covers the core base/comparison scope distinction but does not explain the return payload or the untouched credential/filter parameters, leaving real 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 only 40% schema coverage the description must compensate, and it partly does: it confirms eventTitle and baseExecutionScope (environment + timeWindow) as required and explains the optional comparisonExecutionScope role. However botId, projectApiKey, metadataFilters, release, branchName and platform are left solely to the schema.

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

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

States a specific resource (one event) and action (TrueCoverage drill-down), distinguishing it from the plural get-truecoverage-events by scoping to a single event. The verb 'drill-down' is a bit informal but the intent is clear. It does not name the sibling it complements, leaving some inference to the agent.

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

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

Usage is only implied: the agent must infer that this is the per-event detail view invoked after a list call. There is no explicit when-to-use or when-not-to-use guidance, no prerequisites, and no routing against siblings like get-truecoverage-events or get-truecoverage-event-time-series.

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=false, so the safety profile is covered. The description adds no behavioral context beyond restating the operation, and the parenthetical request-type name ('ListEventMetadataKeysRequest') conveys nothing an agent can act on.

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 compact sentences with the core action front-loaded and no padding. The only waste is the '(ListEventMetadataKeysRequest)' type-name aside, which adds no agent-relevant 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?

For a read-only list tool with no output schema, the description is minimally sufficient — it tells the agent what to pass and what it returns at a high level. It omits any notion of what 'metadata keys' are, whether results are scoped by project, or how they relate to the event-detail tools.

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 67%; botId and projectApiKey are documented in the schema, while the required eventTitle has no schema description. The description compensates by naming eventTitle and its CLI form (--event-title or json-input), which is genuinely useful for the undocumented required parameter. Baseline 3 is appropriate given the mixed 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?

States a specific verb and resource: 'List metadata keys for a given event title.' This is clearly distinguishable from the closest sibling, get-truecoverage-session-metadata-keys, by the event-vs-session scope. However, it never names an alternative, so the differentiation is implicit rather than explicit.

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 offers no when-to-use guidance, no prerequisites, and no mention of alternatives such as get-truecoverage-event-details or get-truecoverage-session-metadata-keys. It only explains how to supply the required parameter.

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, non-destructive and closed-world, so the safety profile is covered. The description adds useful domain semantics (base scope = real-user/primary environment, comparison scope = coverage), but says nothing about result shape, volume, pagination, or cost of wide time windows.

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 core scope distinction is front-loaded and the timeWindow syntax is shown inline via a compact example. The '(ListEventsRequest)' parenthetical and repeated platform enum spelling are mild filler, but the description is dense rather than padded.

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 complex nested-object tool with no output schema and only half its parameters documented, the description covers the essential scope/timeWindow mechanics but omits the credential parameters and filter semantics. It is adequate to attempt a call, not to call it optimally.

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 roughly 50% schema description coverage, the description must carry weight, and it does explain the semantic difference between baseExecutionScope and comparisonExecutionScope plus the two timeWindow forms with an example. But nested fields such as metadataFilters, release, branchName, and botId/projectApiKey auth requirements are left entirely to the schema.

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

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

The description identifies a specific resource: 'TrueCoverage event funnel summaries (ListEventsRequest)', which tells an agent this returns aggregated funnel data rather than raw events. It is distinguishable from siblings like get-truecoverage-event-details or -time-series by the word 'funnel', though it never names those siblings explicitly to draw the contrast.

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 gives real conditional guidance: comparison scope is optional and used 'for coverage', with automationEmitsOnly:true selecting test-tagged emits. It also states the prerequisite 'Prefer list-rum-environments first'. However, it never addresses when to choose this tool over the many other get-truecoverage-* siblings, so selection guidance is only partially covered.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that output is daily granularity per single metric, which is genuine behavioral value, but says nothing about return shape, limits, or how timeWindow affects granularity.

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

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

Two sentences with the purpose front-loaded and no filler preamble. The trailing enumeration of nine metricType values is long and duplicates the schema enum, which costs it a point, but the core is tight.

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 nested-schema tool with no output schema, the description conveys the essential concept (daily per-metric series scoped by environment/timeWindow) but omits meaningful surface area: which fields the baseExecutionScope supports beyond environment/timeWindow, and what the returned series looks like. Adequate but incomplete given the 5-parameter nested schema.

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

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

Schema description coverage is only 40%, so the description should compensate more than it does. It clarifies that baseExecutionScope (environment + timeWindow) is required and lists the metricType enum values, but the enum listing merely duplicates the schema, and it leaves botId, projectApiKey, metadataFilters, platform, and release unexplained.

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

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

States a specific verb+resource: 'TrueCoverage daily time series for one metric (EventTimeSeriesRequest).' An agent can distinguish this from get-truecoverage-events or get-truecoverage-event-details by the 'time series' framing. It does not, however, name a sibling or state the boundary explicitly, so it falls short of a 5.

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

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

The description states what is required to call it ('Requires baseExecutionScope (environment + timeWindow)') but gives no when-to-use guidance, no conditions under which to pick this over the sibling coverage tools, and no exclusions. Requirements are a precondition, not usage guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description adds a real behavioral caveat: metadataFilters on scopes are silently ignored. It does not, however, describe the shape of the returned transition stats.

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?

Compact and front-loaded: purpose first, then required/optional fields, then the caveat. Dense with implementation jargon (request type name, field-name note) but no wasted sentences.

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 6-parameter tool with deep nested objects and no output schema, the description covers invocation essentials but omits what the transition stats contain and any auth/prerequisite context beyond the schema's own notes. Adequate but with clear 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 only 33% schema description coverage, the description must compensate, and it does partially: it names the baseScope/coverageScope vocabulary, flags required vs optional, and warns that scope metadataFilters are ignored. It still leaves botId, projectApiKey, and the scope fields' semantics largely to the schema.

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

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

States a specific verb and resource: 'detailed transition stats between two events'. It is distinguishable from siblings like get-truecoverage-event-details and get-truecoverage-child-event-tree by naming the transition/between-events scope, though it doesn't explicitly contrast with them.

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 tells the agent which fields are required (eventTitle, nextEventTitle, baseScope) and which is optional (coverageScope), plus a 'metadataFilters ignored' caveat, but gives no when-to-use guidance relative to the other truecoverage retrieval tools. Usage is implied rather than routed.

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, and openWorldHint=false, so the safety and idempotency profile is fully covered elsewhere. The description adds only the modest detail that keys are 'observed in RUM' (i.e., derived from telemetry rather than configured), and says nothing about auth requirements or result limits.

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

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

A single sentence with the scope ('session-level') front-loaded and no filler. Every word contributes to identifying the resource and its domain.

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 listing tool with full schema coverage and no output schema, the definition covers what an agent needs to select and invoke it. It could go further by noting how the returned keys relate to the event-level counterpart or whether results are paginated, but 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?

Schema description coverage is 100%, so botId and projectApiKey are already documented in the schema, including the note that the API key is required on every call except a few named tools. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description names a specific verb ('List'), resource ('session-level metadata keys'), and scope ('observed in RUM for TrueCoverage filters'), which lets an agent distinguish it from the similarly named get-truecoverage-event-metadata-keys by the session vs. event granularity. It stops short of explicitly naming that sibling, so it lands just below the top tier.

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?

'for TrueCoverage filters' implies the keys are meant to drive filter construction, but the description never states when to call this versus the event-level metadata keys tool or the related event/child-event-tree siblings. Usage is inferable but not spelled out, and there are no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing exactly what comes back (full plan markdown content, title, platform file path), which matters given there is no output schema. It stops short of mentioning pagination, limits, or auth failure behavior.

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 tight sentences: what it does, what it returns, when to use it. The identifier format is front-loaded with the action, and every sentence carries information an agent needs.

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?

Covers purpose, identifier semantics, return payload, and the situation that selects this tool, which compensates for the missing output schema. The credential requirements live in the schema parameter descriptions rather than the tool description, which is acceptable but leaves the description slightly less self-contained for a tool that can fail on auth.

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 67% schema coverage, the baseline is 3, but the description goes beyond the schema by explaining that userStoryOrdinalIds is the numeric part of US-<n> — the schema itself gives that array no description at all. botId and projectApiKey are already documented in the schema, so the description's marginal contribution is focused and useful.

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

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

States a specific verb and resource (fetch user stories) plus the exact identifier format (ordinal id = numeric part of US-<n>). This is distinguishable from the create-user-story and update-user-story siblings, and the returned content is spelled out. An agent can tell what this tool does without opening the schema.

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 a genuine when-to-use condition: "Use when plan files are not yet synced to the repo." However, it never names an alternative (e.g. get-plans-support-file or get-test-scenarios) or states a when-not-to-use, so the routing is clear but not exhaustive.

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 a safe read-only, idempotent, non-destructive operation. The description adds useful behavior beyond that: includeActions defaults to true, pendingApprovalOnly and assignedToMeOnly scope the list, and latestOnly enables since-last-run scoping. It does not mention the projectApiKey requirement or rate/pagination behavior, but it adds meaningful 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 front-loaded with the purpose, then gives one compact sentence per invocation mode. Each clause maps directly to a parameter combination, with no wasted text.

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

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

For a 12-parameter, multi-mode read tool with no output schema, the description covers the key invocation patterns and defaults needed to call it correctly. It still omits auth requirements and any indication of the response shape, so it is strong but not fully complete.

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

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

Schema description coverage is only 33%, but the description compensates for many parameters by explaining workflowId, limit, offset, pendingApprovalOnly, and assignedToMeOnly for listing; workflowExecutionId for single fetch; and latestOnly with branchName/userId for latest-run scoping. It omits semantics for botId and projectApiKey, which are left to the schema.

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

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

The description states a specific verb and resource: list or fetch workflow executions. It also enumerates three invocation modes, which makes the tool's purpose clear. It does not explicitly differentiate itself from nearby siblings such as list-workflow-catalog or get-execution-history.

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 gives explicit parameter combinations: omit identity args to list, pass workflowExecutionId for one execution, or pass workflowId plus latestOnly=true for the last run. This is strong internal guidance, though it does not name alternative sibling tools or state when not to use this tool.

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

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

Annotations already declare the write/non-destructive/non-open-world profile, so the bar is lower, and the description does add that the response is the ingested execution record (useful given no output schema). However, with idempotentHint=false and an externalId parameter, the critical question of whether re-ingesting the same externalId creates a duplicate or dedupes is left unstated.

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 short sentences with the action front-loaded and no filler. The optional-parameter list is compact, though it is a bare enumeration rather than information-dense prose.

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?

A 10-parameter write tool, but the description covers the identifier choice, the required result, the optional metadata set and the return shape, with auth key guidance carried in the schema. The missing piece is ingestion/idempotency semantics for repeated externalId submissions.

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 only 20%, but the description compensates by enumerating the business parameters it cares about (scenarioOrdinalId, externalId, result, release, testRunLabel, environment, platform, notes). It does not explain how to choose between scenarioOrdinalId and externalId when you have both, nor where externalId comes from, which is the main semantic 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?

Specific verb + resource ('Record a scenario execution result') with the key identifying inputs named immediately. It is clear what the tool does, but it never distinguishes itself from nearby siblings such as manage-test-run or report-agent-action, which an agent could plausibly reach for instead.

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?

'manual or imported' gestures at the two usage contexts and 'Provide scenarioOrdinalId and/or externalId' gives a minimal input rule. There is no explicit when-to-use/when-not and no named alternative, so the agent must infer the boundary with manage-test-run.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) it discloses the auth model, the default role applied, the sign-up email side effect, and the full set of per-email outcomes (INVITED, ALREADY_MEMBER, ALREADY_INVITED, FAILED with failureReason). This is exactly the extra context annotations cannot carry.

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?

Front-loaded with the action and effect, then layered with prerequisites and return values. The second sentence is dense and slightly run-on, packing auth, bot binding, and the CLI restriction together, but no sentence is 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 write tool with no output schema, the description covers the mutation's effect, auth requirements, side effects, and the return shape. Nothing an agent needs in order to call it safely 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?

Schema coverage is 100% so the baseline is 3, but the description adds meaning: the binding-argument path that supplies botId/projectApiKey for bot callers, and the user-confirmation constraint that governs the emails array. It stops short of adding syntax or format detail for individual 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?

States a specific verb and resource ('Invite teammates (by email) to the TestChimp organization'), the effect ('so they can access this project'), and the resulting role ('joins as a Viewer'). No sibling tool shares this action, so an agent can route to it unambiguously.

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?

Gives explicit conditions: requires an OAuth user session whose user is an org admin, QA bots must go through the connector with binding arguments, and the CLI --bot key cannot invite. It also names the exclusion ('Only call with emails the user explicitly confirmed') and points to teamSettingsUrl for role changes/seats.

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/non-destructive, so safety is covered elsewhere. The description adds real behavioral facts — default filter is REAL and results are capped at 100 — but says nothing about pagination, ordering, or cost, and its 'requires testId and/or operationId' precondition contradicts the schema's zero required parameters.

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 short sentences, each carrying distinct information (resource, precondition, defaults/caps), with the core purpose front-loaded. No filler.

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

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

For a 10-parameter read tool with 20% schema coverage and no output schema, the description accounts for only a few parameters. Key filters such as executionId, interactionId, includePayloads, and retryCount are undocumented anywhere, and the stated precondition is inconsistent with 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?

Schema description coverage is only 20% across 10 parameters, so the description carries heavy burden. It clarifies testId/operationId, the interactionType default of REAL, and the 100 cap on limit, but leaves executionId, interactionId, retryCount, includePayloads, and botId entirely unexplained.

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

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

States a specific verb and resource ('List recorded API operation interactions'), which is clear on its own. It does not distinguish itself from the nearest sibling, get-api-operations, which an agent would plausibly confuse it with.

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?

'Requires testId and/or operationId' is the closest thing to a usage rule, giving the agent a precondition for calling. It names no alternatives and no when-not-to-use case, and the 'requires' claim conflicts with the schema where required parameters = 0.

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=false, so the safety profile is covered. The description adds only the 'troubleshooting' framing and says nothing about pagination behavior, filtering, or what event data is returned, so it contributes very little beyond the structured fields.

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 compact sentence with the use-case tag front-loaded and no wasted words. It is well structured, though the extreme brevity is also the source of its other gaps.

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 six-parameter, filterable event-listing tool with no output schema, the description omits filtering semantics and return behavior entirely. Given the complexity and the partial schema coverage, this is not enough for an agent to invoke it confidently.

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?

Six parameters with only 33% schema description coverage, yet the description mentions no filters at all. It does not explain the purpose of eventType, eventStatus, or page, which is exactly where the coverage gap lies and where the description should compensate.

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

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

States a specific verb ('list') and resource ('BunnyShell platform events for an environment'), which is clearly distinguishable from neighboring tools like list-bunnyshell-workflow-jobs. It does not explicitly name any sibling, so it falls short of a 5.

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

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

The leading 'Troubleshooting:' tag implies the use case (diagnosing environment issues), which is a real contextual cue. However, it names no alternative tool (e.g. get-bunnyshell-workflow-job-logs for job-level logs) and gives no when-not conditions, leaving the agent to infer selection.

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 and openWorldHint=true, so the safety profile is fully covered by structured data. The description only adds the troubleshooting framing and environment scoping; it says nothing about pagination, result volume, or 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?

A single front-loaded sentence with the use case placed first and zero filler. It is efficient, though the terseness is part of what leaves the semantic gaps above.

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 no output schema, 4 parameters at 50% coverage, and a paging parameter, one line is not enough. An agent is left without knowing what a job record contains, how to page, or how this differs from the job-logs sibling.

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 50% (botId and projectApiKey are documented, bnsEnvironmentId and page are not), and the description supplies no parameter meaning at all. It neither explains the required environment id nor clarifies how the page parameter drives result paging.

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

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

States a specific verb (list) and resource (BunnyShell workflow jobs) scoped to an environment, which cleanly separates it from siblings like list-workflow-executions and get-bunnyshell-workflow-job-logs. It does not explicitly name the sibling it is not, so it stops short of a 5.

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

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

The leading 'Troubleshooting:' tag implies the intended scenario, which is useful framing. However, it gives no when-not guidance and never points to the adjacent tools an agent would weigh against it, such as get-bunnyshell-workflow-job-logs for a single job's output.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that values are 'distinct' and mentions optional filters, but it does not add behavioral context such as auth requirements, rate limits, or how filters combine.

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 followed by a compact list of optional filters. It is appropriately sized and wastes no space.

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

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

For a tool with 10 parameters, nested objects, low schema description coverage, and no output schema, the description is too thin. It covers the purpose and names optional filters, but leaves important parameter semantics and filtering behavior unexplained.

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 only 20%, so the description should compensate with meaningful parameter semantics. It lists eight optional parameter names and expands the dimension enum values in natural language, but it does not explain what timeWindow, dimensionFilters, or the other parameters mean or how they affect results.

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 a specific verb and resource: 'List distinct execution-job dimension values', enumerates the dimensions, and explicitly links the tool to filtering get-execution-history. This distinguishes it from the sibling get-execution-history, which retrieves history rather than filter 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?

It gives clear context that the tool is for filtering get-execution-history, implying it should be used when the agent needs valid filter values. However, it does not explicitly state when not to use it or name alternative tools for discovering dimension values.

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, destructiveHint=false, idempotentHint=true, openWorldHint=false, so the safety profile is fully covered. The description adds the auth requirement (project API key), but that is largely restated by the projectApiKey schema field. No pagination behavior, default limit, result ordering, or truncation behavior is 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?

Three short sentences, front-loaded with purpose and ending with auth. The filter enumeration is slightly redundant with the schema properties list, but as a scannable capability summary it earns its space.

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

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

A 15-parameter read tool with 13% schema coverage and no output schema needs more than this. The description leaves the singular/plural filter duality unexplained, gives no default or maximum limit/offset behavior, and says nothing about result shape or ordering, which an agent must guess before invoking.

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 only 13% across 15 parameters, so the description needs to carry the burden and it does not. It lists filter names (searchText, statuses, severities, assignee, assignees, labels, release, limit, offset, ordinalIds) without defining any of them, and never explains the critical singular-vs-plural pairs (status vs statuses, severity vs severities, assignee vs assignees) or what ordinalIds are. Listing names already visible in the schema adds little meaning 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?

"Search / filter TestChimp issues in the current project" gives a specific verb (search/filter) and resource (issues) plus project scoping. It also disambiguates from get-issue-details for single-issue retrieval. It stops just short of 5 because what a search returns (IDs? full records?) is never stated.

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 routes the agent to get-issue-details "for one issue by ordinal," which is a real alternative with a stated selection condition. No negative guidance is offered, e.g. when filters are unnecessary or whether calling with zero filters returns everything (required params = 0).

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