nimo

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

Annotations declare readOnly=false, idempotent=true, destructive=false and openWorld=false, so safety is largely covered. The description still adds real behavioral value: the tool returns a ping URL and the exact shell-idiom required to wire it up, plus a verification requirement before claiming success. It does not, however, discuss failure/auth edge cases beyond the wiring caution.

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 ordering from wiring to verification. Every sentence is functional — the `&&` vs `;` rule and the confirm-before-claiming rule are load-bearing. Slightly dense across several imperatives 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 create/monitor mutation tool with an output schema present, the definition covers the full lifecycle: what it sets up, what it returns, how to wire it into the user's command, and how to confirm. Nothing an agent needs 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 params (name, every) are documented there, so the schema carries the semantics. The description implies the schedule concept ('runs on a schedule') and the 'every' enum window of a successful finish, but adds no syntax or constraint detail beyond what the schema already states — 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?

Opens with a precise verb+resource+outcome: watch a scheduled job and alert the user when it stops running. It also names the sibling get_check_in for verification, so an agent can distinguish this setup tool from the check-in read tools (get_check_in, list_check_ins, remove_check_in) 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?

Gives explicit, actionable when-to-use guidance: append `&& curl -fsS <pingUrl>` to the end of the command, never use `;`, then run the job once and call get_check_in before telling the user it is set up. This is unambiguous routing and sequencing, not 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real context beyond them: subject to plan limits, creates a manual mobile site, and returns a siteId consumed by run_audit. Removal being app-only is also useful, though rate/duplicate behavior is 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 zero filler: purpose and return value first, constraint and alternative after. Every sentence earns its place and nothing is buried.

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

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

With an output schema present, the description needn't explain return shape, and it still flags the siteId handoff to run_audit. Combined with the plan-limit caveat and the alternative tool, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so url and name are already documented with formats, bounds, and the hostname default. The description only references the url indirectly ('public site') and adds no syntax or naming behavior beyond the schema, 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 ('Save a public site for repeat checks') plus the concrete outcome (returns siteId for run_audit). It also differentiates itself from the one-off sibling audit_url by name, so an agent can route correctly without 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 conditions: use this for repeat checks, use audit_url for a one-off check, and remove saved sites in the Nimo app rather than via a tool. It lacks guidance on duplicate handling, which matters given idempotentHint=false, but otherwise the when/when-not routing is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: it is a read of stored results, it will not trigger new measurement, and output is ordered with verified regressions first. It stops short of saying what happens for sites with no completed audit.

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 zero filler; the core scope and the 'stored results only' constraint come first, and routing guidance follows. 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 an output schema present, return-value detail is unnecessary, and the description covers scope, ranking order, and alternative tools. Safety traits are handled by annotations, so nothing required 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?

Zero parameters, so the schema imposes no documentation burden and the baseline is 4. The description correctly spends no words on parameter syntax and instead covers scope and alternatives.

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 ('Review') plus the exact resource and scope ('the latest completed audit for every site') and adds a ranking behavior ('rank verified regressions first'). An agent can distinguish it from get_audit_report or get_audit_history 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?

Explicitly bounds usage with 'Uses stored results only; it does not start new audits', then names two alternatives with the condition that selects each: run_audit for re-measuring a saved site, audit_url for a one-off URL check. This is the when/when-not/alternatives pattern done properly.

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 readOnlyHint=false, idempotentHint=false and openWorldHint=true, and the description explains the reason: 'Each call runs another check, including requests for a different section,' which clarifies the non-idempotent, stateless behavior. The 'without saving a site' note adds meaningful side-effect context beyond the annotations, though it does not cover rate limits or auth needs.

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, then the per-call behavior, then the alternative routing. 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?

With an output schema present, return values need not be described; the description covers ephemerality, per-call semantics, section selection, and sibling alternatives. An agent has everything needed to select and invoke it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the section enum and its default. The description reinforces that choosing a section up front matters because switching sections costs another call, but adds little syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Check a public URL's mobile performance and page metadata') plus the key scope qualifier 'without saving a site'. This clearly distinguishes it from the persisted-workflow siblings add_site and run_audit.

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: use add_site then run_audit for saved, comparable checks, and get_audit_report to read an existing saved report. Both alternatives and the condition selecting them are named.

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 say readOnlyHint=false and destructiveHint=false; the description adds material context the annotations cannot: share publishes a public expiring link, it needs manage permission, and results are valid only when both audits share strategy and device, with source-changed metrics flagged inconclusive. This is rich disclosure beyond structured data and is consistent with readOnlyHint=false.

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 clauses, no waste: action first, then the share guard, then the result-validity caveat. Front-loaded with the core purpose and each sentence 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?

Output schema exists so return format need not be explained, yet the description still adds the crucial output conditionality (shared strategy/device, inconclusive deltas) that an agent needs to interpret results. Combined with the share-safety guidance, nothing material is missing for a 4-param tool.

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

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

Schema coverage is 100%, so baseline is 3. The description raises it by adding governance semantics the schema lacks: share requires explicit approval and manage permission, and defaults to off. The A/B orientation is already in the schema, so no further credit is earned there.

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 ('Compare two audits') with a unique role no sibling tool fills (get_audit_report, share_report, get_audit_history all do different things). It adds the default non-publishing posture and the delta computation condition, so an agent knows exactly what it 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?

Gives explicit conditions for the risky path: set share:true 'only with explicit approval and a connection that has manage permission.' This is clear when/when-not guidance for the write behavior. It stops short of routing the agent away from or toward sibling audit tools, so 4 rather than 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 cover the safety profile (readOnly=false, destructive=false, non-idempotent), and the description adds what annotations cannot: the return is a secure expiring setup URL, the operation is incomplete until the user authorizes, and the correct verification tool. This is behaviorally rich beyond 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?

Four short sentences, front-loaded with the action and return value, followed by the critical constraint and the follow-up step. No sentence is redundant.

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?

An output schema exists, yet the description still conveys the one thing an agent must act on (surfacing the URL and not treating it as success). For a single-parameter connection tool, 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 coverage is 100%, and the schema already documents siteId as the 'Owned Nimo site ID from list_sites'. The description reinforces the 'owned Nimo site' framing but adds no syntax or format detail beyond the schema, 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 (Connect), resource (PostHog), and scope (an owned Nimo site). It clearly distinguishes itself from the read-side sibling by naming get_posthog_connection_status as the verification step.

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

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

Explicitly prescribes the workflow: show the exact URL, never ask for API keys in chat, and recognize that a link is NOT a completed connection — then check status after authorization. Both when-to-use and what-not-to-do are 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 this is a write operation (readOnlyHint=false), not idempotent, and non-destructive, so the safety profile is covered. The description adds a useful behavioral distinction ('does not prove the flow works'), but does not mention side effects, approval requirements, or what the created journey contains.

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 no waste. The core purpose is front-loaded in the first sentence, and the next-step instruction follows logically.

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

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

The tool has an output schema and full parameter descriptions, so return values and params are covered elsewhere. The description compensates by clarifying the tool's role (creating, not validating) and the follow-up action, leaving little missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the scoping constraint 'for an owned site' which loosely maps to siteId and startUrl origin requirements, but does not document prompt, frequency, or parameter interactions beyond what the schema explains.

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 ('Save one customer goal', 'creates a learning journey'), and clarifies a scope constraint ('for an owned site'). It is distinguishable from siblings like add_site or add_check_in, but the repo-specific term 'learning journey' is not further defined for an agent unfamiliar with 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?

It explicitly tells the agent what to do next ('Call run_journey next to start the first private exploration'), which is strong sequencing guidance. It lacks explicit when-not-to-use guidance (e.g., versus update_journey or list_journeys), but the next-step instruction is concrete.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile needs no restating. The description adds the useful temporal framing ('prior audits', 'the trend'), but says nothing about ordering, retention, or whether history is empty for new sites. Output schema exists, so return shape is not its burden.

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

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

Two short sentences, and the highest-value content (the call trigger) is front-loaded. Nothing is padded or repeated from the name or title.

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

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

With an output schema present and full parameter coverage, the description only needs to supply selection guidance and it does. Minor gap: how the default limit of 10 behaves for trend analysis is left entirely to 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 100%, so both parameters (siteId, limit with min/max/default) are already documented in the schema. The description adds no semantics beyond that, which is the expected baseline when the schema does the work.

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 ('Returns prior audit metrics') plus the analytical purpose ('see the trend'), which separates it from get_audit_report and compare_audits. It stops short of naming the siblings it is not, so differentiation is inferred 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?

'Call before a large change or when investigating a regression' gives a concrete trigger condition, stronger than implied usage. It never names alternatives such as compare_audits for side-by-side comparison, so the when-not case stays open.

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), so the bar is lower. The description adds real context beyond them: the data is *saved* rather than freshly gathered, focused sections can be read 'without running another audit', and get_seo_evidence can inspect deployed HTML while this cannot. It stops short of stating staleness windows or refresh semantics.

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, front-loaded with the primary capability, then the section routing tip, then the alternative-tool guidance. No filler and nothing repeated from the schema or annotations.

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?

An output schema exists, so return values need no elaboration. With purpose, sibling routing, the saved-vs-fresh distinction, and the noindex caveat all covered, an agent has everything needed to call this correctly rather than reaching for get_seo_evidence or run_audit.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds selective meaning beyond the schema: section:'pageMetadata' enumerates what it returns (title, description, canonical, social-preview evidence), the default 'summary' is characterized, and 'full' is flagged as a last resort. That is more than the enum alone conveys.

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 ('Read saved performance causes, metrics, and page-metadata health') and immediately scopes the resource further with section:'pageMetadata'. An agent can distinguish it from get_seo_evidence without 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 routing rules: use section:'pageMetadata' for the audited page's saved metadata, but for fresh SEO / organic traffic / noindex questions start with get_seo_evidence instead. It also warns that empty performance recommendations do not establish SEO health, which is a genuine when-NOT-to-conclude rule.

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, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: the expected poll cadence, the 3-minute bound, and that structured completion carries compact reportSummary evidence once the stored report is ready.

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 filler, with the trigger condition front-loaded before the polling mechanics. 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?

An output schema exists, so return values need not be enumerated, yet the description still flags the notable reportSummary field. For a one-parameter polling tool with full annotation coverage, 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 coverage is 100% and there is a single auditId parameter, so the schema already carries the semantics. The description only implies that the ID comes from run_audit's response and adds no format or sourcing detail beyond that, which is the baseline case when the schema does the heavy lifting.

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 positions this as the poller for an audit kicked off by run_audit and indicates it surfaces completion plus a reportSummary, which lets an agent distinguish it from run_audit, get_audit_report, and get_audit_history. It never states outright 'returns the current status of an audit', so the core verb+resource is inferred from the name and the trigger sentence rather than declared.

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 trigger ('Call after run_audit returns queued or running') plus concrete polling policy (every 20 seconds, up to 3 minutes) is unusually actionable guidance. It stops short of naming the follow-up alternative (e.g. get_audit_report once the report is ready), so the routing after completion is left implicit.

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 state readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful timing context (post first job run) but does not disclose error behavior, permission needs, or what happens if the check-in has not arrived.

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

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

The description is a single, efficient sentence with no wasted words. It is front-loaded with the usage condition, though it could be strengthened by leading with the tool's purpose.

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

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

The tool is simple, and the schema, annotations, and output schema cover most structured details. The description supplies usage timing but omits what the tool returns and how it differs from list_check_ins, leaving a small but meaningful 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?

The single parameter checkInId is fully documented in the schema, including that it is returned by add_check_in or list_check_ins. The description adds no parameter meaning beyond that, so the baseline of 3 applies given 100% schema coverage.

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

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

The description only says when to use the tool ('after running the job once') rather than stating the operation it performs. It implies confirming a check-in but never says it retrieves a check-in record or what information it returns. The purpose is therefore vague, though not a pure tautology.

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 a clear condition for use: after running the job once, to confirm that the first check-in arrived. However, it does not name alternatives such as list_check_ins or add_check_in, nor does it say 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the ownership requirement and the bounded return scope (ten memory versions, three latest runs). It does not mention pagination or rate limits, keeping it short of 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 tight sentences with no padding; the core read scope is front-loaded and the follow-on sentence supplies the practical destination for the data.

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

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

With an output schema present, return values need not be spelled out, and the description covers purpose, ownership constraint and result cardinality. The one gap is the absence of explicit routing against the closely related get_journey_run and list_journeys siblings.

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?

Only one parameter and schema coverage is 100% — the schema already documents journeyId and points to list_journeys as its source. The description adds nothing further about the parameter, 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 ('Read one owned journey') and scopes the payload (up to ten memory versions, three latest runs), which distinguishes it from the sibling get_journey_run. It never names list_journeys or get_journey_run directly, so differentiation is implied by scope rather than 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?

The second sentence ('Use the private Nimo URL for replay or memory review') hints at the scenario that motivates the call, but it is oblique and gives no explicit when-to-use vs get_journey_run, list_journeys, or update_journey. Usage is only implied.

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), so the bar is lower. The description adds genuinely useful, non-obvious behavior: that in-flight responses carry pollAfterMs for re-polling, and that terminal execution status and website outcome are distinct and must be reported separately without inferring success. It stops short of covering error/permission behavior despite the "owned" qualifier.

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 action, then the polling detail, then the critical interpretation warning. No padding or restatement of the name; every sentence carries load.

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

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

With an output schema present, the description needn't explain return fields, and annotations carry the safety profile; the remaining gaps are explicit auth/ownership explanation and error behavior. Its coverage of polling cadence and dual-status interpretation makes it essentially complete for correct invocation.

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

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

Schema description coverage is 100% and both params are documented there (runId: "returned by run_journey"; journeyId: "Owned journey ID"). The description's only added meaning is the "owned" ownership constraint, which is minor; baseline 3 applies when the schema does the heavy lifting.

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 ("Poll an owned journey run") that clearly distinguishes a run-poll from the sibling get_journey. It does not explicitly contrast against the closest alternative (run_journey, which initiates the run, or get_journey which fetches config), 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?

The mention that queued/running results include pollAfterMs implies a repeated-polling workflow, which is useful implicit guidance. However, there is no explicit when-to-use/when-not, no statement that this is the follow-up to run_journey, and no named alternative, so usage is only implied.

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 the description adds substantial context beyond them: a fixed 28-complete-UTC-day window, up to 12-hour caching, hostname-exact scoping, independent (non-funnel) event counts, and the caveat that missing/failed states are not zero traffic. This is exactly the behavioral context an agent needs before trusting the numbers.

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, front-loaded with the core action, then windowing/caching, then interpretation caveats, then a security note. Every sentence carries distinct, non-redundant information; nothing is 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?

With annotations covering safety and an output schema handling return structure, the description supplies the remaining essentials: freshness/staleness, scope, and semantic pitfalls in reading the data, plus a prompt-injection warning. Nothing an agent needs to invoke or interpret 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% and the single siteId parameter is already documented as 'Owned Nimo site ID.' The description adds minor meaning by clarifying scope is 'the site's exact hostname,' but cannot go much beyond the schema for a one-param tool, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Read bounded aggregate site analytics through the PostHog connection.' It is clearly distinguishable from the connection-management siblings (connect_posthog, get_posthog_connection_status) by centering on reading analytics data rather than managing the connection.

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

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

The phrase 'through the PostHog connection already stored securely by Nimo' implies a prerequisite (a connection must exist) but stops short of naming an alternative tool or stating explicitly when to use this versus get_posthog_connection_status or get_site. Usage is implied rather than directed.

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 safe-read profile (readOnly, idempotent, non-destructive), and the description adds real behavioral value on top: the meaning of each terminal state, the crucial caveat that connected+no_matching_events does NOT mean zero traffic, and that attempt status expires alongside the setup link. That last point is time-sensitivity the annotations cannot express.

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 tight sentences with no filler, front-loaded with the action and its trigger, followed by the state interpretations and the expiry caveat. Every sentence carries operational weight.

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

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

With an output schema present, return values need not be spelled out, and the description still covers the highest-risk gaps: how to read partial success and the do-not-misreport warning. Nothing an agent needs to call and correctly interpret 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?

One parameter with 100% schema description coverage, so the schema already explains attemptId and its origin. The description restates that provenance plus useful context (it is produced after user authorization), but adds no format or validation detail beyond the schema. Baseline 3 applies when the schema carries the parameter load.

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 ('Check the attemptId ... status') and anchors it to the sibling that produces the input (connect_posthog). An agent can distinguish this read-side status check from the connect_posthog initiation call without 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 an explicit trigger condition: call this after the user completes authorization, using the attemptId returned by connect_posthog. It also frames how to act on results ('Pending/failed/expired are not connected'), but names no alternative tool for the not-connected case, so it stops short of full when/when-not 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 carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds non-obvious operational context: URL Inspection reads consume Search Console inspection quota. That quota disclosure is real value beyond annotations; it does not, however, discuss latency or failure modes for the expensive multi-fetch paths.

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 one-line purpose before the enumerations, and the closing sentence handles routing efficiently. The middle enumeration sentence is long and dense, but each listed item maps to a distinct output section rather than being 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?

Output schema exists, so return-shape detail is not required, yet the description still signals what the agent will get and how costly the optional paths are. Scope, read-only nature, quota implications, parameter caps, and the sibling alternative are all present, leaving no material gap for a high-complexity, 7-parameter tool.

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

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

Schema coverage is 100%, so 3 is the baseline and the schema already documents limit/offset/dates. The description goes further by explaining intent for two parameters — inspect is capped at 20 and should only be raised when index state is needed, contentPages is capped at 25 and defaults to 10 — which adds decision-level meaning the schema's terse ranges do not.

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+scope: 'Site-wide search coverage for one owned site', then enumerates the concrete artifacts it returns (sitemap vs. impressions gaps, submitted sitemaps, URL Inspection status, duplicate/short pages). It explicitly contrasts itself with get_seo_evidence, so an agent can separate the two without 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?

Names the alternative and the condition that selects it: 'Use get_seo_evidence for one page's queries, HTML or analytics', implying this tool is for site-wide coverage. It also gives per-parameter usage rules ('set it only when index state is needed' for inspect). It stops short of stating a full when-not-to-use boundary beyond 'no audits or edits'.

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, but the description adds cost and side-effect detail beyond them: Ahrefs allowance is consumed by fresh ahrefs/backlinks/refresh reads, saved evidence is reused by default, and clicks/sessions/estimates 'must never be added or relabeled'. That is materially useful behavioral context an agent cannot get from the annotation block.

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 'START HERE' and the core purpose, so an agent gets the gist immediately. But it is a dense ~170-word run-on paragraph whose sentences blend routing, parameter semantics and caveats, and it partly restates schema-level freshness/refresh semantics rather than only adding new 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 15-parameter read tool with an output schema (so return values need not be explained), the description covers purpose, routing, cost of refresh, source selection, scope semantics and interpretation pitfalls ('Empty performance recommendations do not prove technical SEO health'). Nothing an agent needs 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 coverage is 100%, so the baseline is 3, and the description does add real meaning for key parameters: it pairs refresh:true with sources:[page] for HTML verification, distinguishes freshness:missing from fresh by cost, and clarifies scope:site means the owned origin. It still leaves a few parameters (dimension, comparePrevious, offset, discoveryDetail) to the schema alone.

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 ('Read SEO evidence for one owned page, with source, scope, units and limitations') and explicitly positions itself as the 'START HERE' entry point for SEO work. It names the sibling it is not (get_search_coverage for site-wide sitemap coverage, pages without impressions, duplicate content), letting an agent route without 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 branches: refresh:true sources:[page] to verify deployed HTML, freshness:missing to recover absent evidence without paid Ahrefs reads, freshness:fresh for live reads, scope:site for the exact owned origin, backlinks for referring domains. It also states exclusions ('No audits, publication or edits') and a concrete alternative (get_search_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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world, so the safety profile is fully covered. The description adds essentially no behavioral context beyond that — no permission requirements, no rate limits, no freshness/staleness caveats — so it contributes little on this dimension.

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 tight sentence with no filler. The trigger condition is front-loaded, though the actual purpose ('see its latest metrics...') arrives second, slightly deferring the what behind the when.

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?

An output schema exists so return values need no explanation, and the description roughly matches the expected payload (metrics, configuration, uptime). It is adequate but stops short of the one thing that matters here: how it relates to the overlapping siblings get_uptime_status and list_sites.

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?

Only one parameter (siteId) and schema description coverage is 100%, so the schema already documents it fully. The description adds no format, sourcing, or lookup guidance for the ID, making this the baseline case where the schema carries the load.

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 (get a site) and enumerates what it returns: latest metrics, configuration, and uptime status. An agent can grasp the target of the call, but the description never distinguishes it from siblings that overlap heavily (get_uptime_status, list_sites), leaving purpose clear but undifferentiated.

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 sequencing guidance ('call after selecting a site', 'before deciding what to do next'), which implies usage context. However, it names no alternative and gives no exclusion, despite get_uptime_status covering part of the same ground, so the agent must infer when this beats the 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 this a safe, idempotent read, so the description instead spends its budget on the genuinely non-obvious behavior: a null lastCheckedAt means no check exists and the default currentStatus is NOT evidence the site is up, and null percentages mean no measurements. This is exactly the trap-avoidance context annotations cannot convey.

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 read operation is front-loaded, followed by the negative scope and then the null-value caveats, with the alternative tool named last. 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 single-param read tool with full annotations and an output schema, the description covers everything needed: what it returns, that it does not trigger a live check, the null/absent-data semantics, and where to go for page-speed measurement.

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% for the single siteId parameter and its 'not a URL' warning is already in the schema, so the description adds no parameter syntax or format detail. Baseline 3 is appropriate when the schema fully documents the input.

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 ('Read a saved site's latest availability check') and enumerates exactly what is returned: response time, 24h/30d uptime percentages, and ongoing incident. It is clearly distinguishable from the audit-oriented siblings.

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 bounds the tool ('Does not probe the site now or start monitoring') and routes the agent elsewhere for a related need ('Use audit_url or run_audit to measure page speed instead'). Both when-to-use and when-not-to-use are 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, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful semantic detail that check-ins represent watched-job liveness, but says nothing about result scope, ordering, or volume. Appropriate but not rich.

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

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

A single sentence with no wasted words. The core purpose is front-loaded in the first two words.

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

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

An output schema exists, so return values need not be explained, and zero parameters plus full annotation coverage means the burden on the description is low. It is adequate, though it omits any linkage to the add_check_in/get_check_in/remove_check_in family that would help an agent choose correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level meaning is missing.

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 clarifies the resource semantically: watched jobs plus each one's check-in status. That goes beyond the bare name. It does not, however, distinguish itself from siblings like get_check_in or list_watched_pages.

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

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

Usage is implied by the name and the phrase 'jobs being watched,' so an agent can infer this is the collection-level view. There is no explicit when-to-use statement, no mention of when to prefer get_check_in (single) or list_watched_pages, and no prerequisites noted.

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 read-only/idempotent safety profile, and the description adds genuinely new context: the returned fields (property/account names, stream hostnames, traffic evidence, saved selection), pagination via nextOffset, and the interpretation caveat that empty recent traffic does not prove tracking is missing. This is rich behavioral disclosure beyond 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?

Purpose and pagination guidance are front-loaded, and every sentence carries actionable content (candidates, caveats, next tool). It is dense and packed into a single block, but there is little waste.

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

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

With an output schema present and annotations covering safety, the description still supplies the workflow (paginate, present candidates, then select), the prerequisite source of siteId, and the key interpretation caveats. 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 coverage is 100%, so limit/offset/siteId are already documented; the schema's offset field even repeats the 'use nextOffset to continue discovery' guidance found in the description. The description adds no syntax or format detail beyond what the schema provides, 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 and resource ('Find Google Analytics properties for the selected site using connected accounts'), and its scope is clearly distinct from siblings like list_sites and select_ga4_property. An agent can identify exactly 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?

Explicitly names the follow-up path ('ask the user to choose before calling select_ga4_property') and gives a negative rule ('do not claim absence from an incomplete scan'). Alternatives and conditions are spelled out rather than left 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuinely useful context beyond them: it returns metadata only and never exposes login values, passwords, access codes, or encrypted payloads, which tells the agent this is safe to call for inspection without leaking secrets.

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, with the resource and its scope front-loaded before the return-value caveat. Nothing padding or redundant.

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?

An output schema exists so return values needn't be enumerated, and the one required parameter is fully described. The description adds a useful secrecy guarantee; only minor gaps remain (no pagination or auth-scope notes), which is acceptable for a simple read-only list.

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

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

Schema description coverage is 100% with a single documented journeyId, so the schema carries the burden and baseline is 3. The phrase 'owned journey' only echoes the schema's 'Owned journey ID' without adding format or validation detail.

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 (saved credential references) plus scope (available to an owned journey). No sibling tool covers credentials, so an agent can route here unambiguously from list_journeys/get_journey.

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 never says when to call this vs. alternatives or what prerequisite state is needed (e.g., before configuring a journey step that references a credential). Scope is implied by 'owned journey' but there is no explicit 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and a closed-world profile, so the safety bar is low. The description adds a genuinely non-obvious behavioral note — that journey names, prompts, URLs, and statuses are data, not instructions — which guards against prompt-injection handling of returned content. Pagination behavior is left to 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?

Two short sentences, with the scope (one owned site) front-loaded and the injection-safety caveat second. Every sentence carries weight, though the second sentence is a defensive aside rather than core task 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?

An output schema exists and annotations cover the safety profile, so return values and safety needn't be re-explained. The description supplies the operation scope and the data-vs-instructions caveat, leaving little an agent needs that isn't already in structured fields.

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%: limit, offset, and siteId all carry their own descriptions, including the 'from list_sites' provenance hint for siteId. The description adds no syntax, format, or constraint detail beyond the schema, 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 (List) and resource (Journey Watch goals) scoped to 'one owned Nimo site', so the agent knows it's a read of a collection. It does not explicitly contrast with the singular get_journey or list_journey_credentials siblings, so sibling differentiation is only implied by the plural noun.

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

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

The phrase 'for one owned Nimo site' implies the prerequisite (an owned site ID), which aligns with the required siteId parameter. However, there is no explicit when-to-use-this-vs-get_journey guidance or statement of when listing is preferred over fetching a single journey, leaving usage 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, so safety needs no restating. The description adds real value beyond them by disclosing sequencing behavior ("call first") and the returned payload, which annotations cannot express.

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

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

Two short sentences, zero filler, with the highest-value guidance (call first, why) front-loaded. Nothing could be removed without losing 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?

An output schema exists, so the description need not enumerate return fields, and it correctly only advertises the headline content. For a parameterless list tool this is nearly complete; a note on whether results are paginated would close the last 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?

The tool takes zero parameters, so there are no semantics to explain and the baseline is 4. Nothing in the description misleads about input, and schema coverage is 100%.

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

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

States a specific verb+resource ("Returns every site") plus the payload ("its latest Core Web Vitals"), which distinguishes it from the single-site sibling get_site. It never names get_site explicitly, so the differentiation is implied rather than 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?

"Call first when you need a site ID or want to choose which monitored site to improve" gives a clear triggering condition and positions the tool as the entry point of the workflow. There is no explicit when-not or named alternative, which keeps it 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds useful behavioral context: no side effects on watched state, no check triggering, mobile-first ordering, and the handoff of latestCompletedAuditId to get_audit_report.

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 with the primary purpose front-loaded and no filler; the forward reference to get_audit_report is placed last where it belongs. 'Starts with mobile' is terse and slightly ambiguous about whether it describes ordering or a default filter, which costs a point.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile; the remaining input semantics live in the schema. The description is essentially complete for a simple paginated read, with only the ambiguous 'Starts with mobile' phrase left unresolved.

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 limit, offset and siteId are fully documented in the schema and the baseline is 3. The description adds no parameter-level meaning (no note on paging interaction or siteId format), and its mention of latestCompletedAuditId refers to an output field rather than an input, which does not 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?

The description gives a specific verb and resource ('see its watched pages') and enumerates the returned data (automatic-check state, per-site cadence, latest page-report IDs), so the agent knows exactly what comes back. It implicitly distinguishes itself from list_sites by scoping to watched pages within one site, but never explicitly contrasts with sibling tools, keeping it 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?

It states a clear precondition ('Call after choosing a site') and two exclusions ('does not start checks or change what is watched'), which is real when/when-not guidance. It also routes the agent forward to get_audit_report, though it does not name an alternative list tool for the case where the agent wants unwatched pages or site-level 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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds genuinely new behavioral context: that memory, credentials, and history survive the pause. It stops short of describing what happens to in-flight runs or how to resume.

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

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

Two short sentences with zero filler; the core action is front-loaded and the preservation guarantee follows immediately.

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

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

For a single-parameter state-change tool with an output schema and full annotation coverage, this is nearly sufficient. The only real gap is the absence of lifecycle guidance about when pausing is appropriate versus resuming or re-running.

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% for the single journeyId parameter ('Owned journey ID'), so the schema carries the meaning. The description adds nothing about the identifier beyond the existing 'owned' qualifier, which matches the baseline for full coverage.

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

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

The description states a specific verb and resource ('Pause an owned journey'), making the operation unambiguous. It does not, however, distinguish itself from the obvious sibling resume_journey or explain the inverse relationship.

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 this applies to an active journey, but there is no explicit when-to-use statement, no mention of prerequisites (e.g., journey must be running), and no routing to alternatives like resume_journey or run_journey.

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, readOnlyHint=false, and idempotentHint=true, so the safety profile is known. The description adds real value by making irreversibility explicit ('This cannot be undone') and by clarifying the side effect is 'stop watching a job', which annotations do not convey. It still says nothing about permissions, scope of deletion, or rate limits.

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

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

Two sentences, no filler, with the action stated first and the irreversibility warning immediately after. Nothing is wasted.

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 output schema present, return values need no explanation, and the destructive annotation plus the 'cannot be undone' warning covers the risk profile for a one-parameter mutation. The remaining gap is the absence of any guidance on when to remove versus pause a journey or check-in.

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 single parameter (checkInId) is fully documented in the schema, including its origin from add_check_in or list_check_ins. The description contributes nothing beyond that, 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 ('stop watching', 'remove') and resource ('check-ins'), and the phrase 'its check-ins' ties it to a job. It is clearly distinguishable from add_check_in, get_check_in, and list_check_ins 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as pause_journey or whether this is reversible by re-adding a check-in. The usage context is only implied by the verb.

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 idempotency and lack of destructiveness, so the bar is lower. The description adds genuinely non-obvious state preconditions (paused state, approved memory) that the annotations do not convey; it stops short of describing failure behavior when the journey is not in that state.

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

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

Two sentences, no waste, with the action and precondition front-loaded and the disambiguating clause placed last. Every sentence earns its place.

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

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

A one-parameter tool with an output schema, so return values need not be explained, and the annotations carry the safety profile. The description supplies the missing state preconditions; only failure/error behavior is left implicit.

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

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

Schema description coverage is 100% with a single 'Owned journey ID' parameter, so the baseline is 3. The description reinforces the ownership constraint but adds no format or sourcing detail beyond what the schema already provides.

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

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

Specific verb ('Resume') plus resource ('owned paused journey'), with a scope qualifier and an explicit negative boundary ('This does not start a run') that separates it from run_journey. An agent can distinguish this from its siblings 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?

States the precondition for use (journey must be owned, paused, and have its memory approved) and clarifies it is not the run-triggering tool. It does not name run_journey explicitly as the alternative, keeping it a step 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 declare non-read-only, open-world, non-idempotent behavior, and the description adds real context beyond that: it consumes allowance (quota cost), wait:true may still return pollAfterMs so the caller should poll get_audit_status for up to 3 minutes, and it explicitly disclaims that a run proves indexing. Missing only details like whether results are stored/reused, but the operational caveats are unusually strong.

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 and front-loaded, with the primary action, its cost, and its polling contract in the first sentence. Semicolon-chaining makes it slightly choppy to parse, but every clause carries routing or behavioral information and nothing is redundant.

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?

An output schema exists, so return shape needn't be explained. Given a 3-parameter tool with 100% schema coverage and rich annotations, the description still supplies the quota cost, async/polling contract, strategy tradeoff, and sibling routing rules an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description genuinely adds beyond the schema: the fact that wait:true 'may still return pollAfterMs' plus the follow-up polling window is not in the property description, and the quick-vs-full tradeoff is framed as an iteration/evidence decision rather than just a speed setting.

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 ('Start a saved-site audit') and immediately distinguishes itself from the closest siblings: audit_url for unsaved URLs and get_seo_evidence for deployed-HTML evidence. An agent can route among audit_all_sites, audit_url, and run_audit from this text 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 explicit when-to-use rules for the strategy enum ('quick for iteration and full for comprehensive evidence'), names the alternative for unsaved URLs ('Use audit_url only for performance on unsaved URLs'), and redirects to get_seo_evidence with exact parameters for indexing and canonical checks. Exclusions and alternatives are both 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 cover safety (not read-only, idempotent, non-destructive), but the description adds the critical async behavior: 'Returns immediately—poll get_journey_run at pollAfterMs', which is not in annotations. It also guides idempotent retry ('Reuse the same requestId if retrying an uncertain call'), directly reinforcing idempotentHint with actionable instructions.

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

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

Three tightly packed sentences, each earning its place: start behavior, mode-dependent behavior, polling and retry instructions. Front-loaded with the core action and scoping constraint.

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 async start-operation with an output schema and rich annotations, the description covers the key operational details: private run, mode semantics, resume prerequisite, async polling, and idempotent retry. Minor gap: doesn't mention what the return object contains, though the output schema covers this; still, it's a model example of a compact but complete run tool.

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

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

Schema coverage is 100% and both parameters are documented with descriptions. The description adds only the retry context for requestId; it does not expand on journeyId semantics. Baseline 3 is appropriate since the schema already does the heavy lifting.

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: 'Start one private browser run.' The destination is clear and distinguishes it from get_journey_run (poll) and create_journey (define). It doesn't explicitly name siblings, but the scope of the operation 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?

Gives concrete when-to-use guidance for journey modes ('Learning/review journeys are explored; active journeys replay approved memory') and an explicit prerequisite ('Resume a paused journey first'), which routes the agent to resume_journey. No explicit when-not-to-use beyond that.

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 cover the safety profile (not readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: it validates ownership and live property access, does not install tracking or alter Google settings, and property:null explicitly clears the selection. It stops short of describing failure/error behavior when validation fails, so it is strong but not exhaustive.

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 is front-loaded and the prerequisite flow follows logically, with each sentence carrying instructions or constraints. It is somewhat dense and the closing sentence about 'Fresh SEO and AI referral queries retain the exact site hostname filter' is tangential and vague relative to the rest.

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

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

With an output schema present, return values need not be explained, and the description still covers prerequisites, confirmation gating, validation, and the non-actions it performs. The one loose end is the unexplained hostname-filter sentence, which leaves a behavioral consequence under-specified.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description ties parameters together by noting the property and connectionId must come from the prior list call and restates the property:null clearing behavior. This relational context adds modest value beyond the per-field schema text.

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 up front: 'Remember the user's explicitly chosen GA4 property for this site.' It also names the sibling it depends on (list_ga4_properties / listGa4Properties), so an agent can distinguish this selection step from the discovery step 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?

Gives explicit ordering and gating: use list_ga4_properties first, present name and hostname evidence, and call only after explicit user confirmation, never on a guess. This is clear when-to-use guidance with a stated precondition, not 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 readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description usefully adds that the resulting link is public and expiring, which is behavioral context beyond the structured fields; it does not address revocation or auth requirements, keeping it short of a 5.

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

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

Two sentences, both front-loaded with the action then the parameter distinction. No filler, and the most important information (what it creates) leads.

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?

An output schema exists so return values need not be described, and annotations cover the safety profile. Purpose and both ID roles are covered; only minor behavioral details (link revocation, sharing scope beyond 'public') are absent, which is acceptable for this tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the auditId/compareAuditId roles. The description restates essentially the same semantics (auditId = newer/current, compareAuditId = earlier) without adding format, defaults, or edge-case detail. Baseline 3 is correct.

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 public, expiring Nimo report link') and immediately disambiguates the two ID parameters, so an agent understands the sharing behavior without opening the schema. It stops short of naming a sibling (e.g. compare_audits) to differentiate from, so it is clear but not maximally distinguishing.

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

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

The description gives clear context for the two invocation modes: single-report sharing by default versus before-and-after comparison when compareAuditId is passed. It does not state when to prefer this over sibling tools like compare_audits or get_audit_report, so there are no explicit exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the journey must be "owned" (a permission/scope constraint) and repeats the at-least-one-field validation rule, but says nothing about failure modes or reversibility of a schedule change.

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

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

Two short sentences with zero waste; the capability is front-loaded and the validation constraint follows immediately. Nothing extraneous.

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

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

With a full output schema, 100% parameter coverage, and annotations covering the safety profile, the description supplies everything an agent needs to call this correctly: ownership requirement, the two updatable fields, and the minimum-field rule.

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 name, frequency, and journeyId are already documented in the schema, including the enum values. The description's mapping of "rename" to name and "schedule" to frequency adds only light semantic reinforcement, not new information.

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

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

States specific verbs (rename, change schedule) and the resource (a journey), so an agent knows exactly what mutation this performs. It implicitly distinguishes itself from create_journey, get_journey, and pause/resume_journey, though it doesn't name any 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?

"At least one field is required" gives a useful invocation constraint, implying usage over a dedicated tool when both name and schedule change at once. However, it never says when to prefer pause_journey/resume_journey for schedule control or what prerequisites exist, leaving alternatives to inference.

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