PreShiftIQ

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds modest behavioral context by stating it returns the platform description plus the URL to start an assessment, but with an output schema present this is largely redundant.

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

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

Three sentences, front-loaded with the purpose, then the usage trigger, then a coverage list. The vertical enumeration is somewhat long but it is the tool's actual content scope rather than filler.

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

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

For a zero-parameter read-only tool with an output schema, the description covers what it does, when to call it, and what it returns. The only meaningful gap is not distinguishing itself from explain_matching, which an agent comparing siblings would have to infer.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool is 4. Nothing in the description misrepresents the empty input schema.

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

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

The description states a specific verb and resource: 'Describes PreShiftIQ and how its vendor matching works,' and enumerates the domain areas it covers (TMS, dock scheduling, ELD, etc.). It is clearly distinct from status/catalog siblings, though it does not explicitly separate itself from the potentially overlapping explain_matching sibling.

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

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

'Use this when a user asks what PreShiftIQ is or how it matches the client... with vendors' gives an explicit trigger condition. It stops short of naming alternatives or exclusions (e.g., when to prefer explain_matching over this), so it is clear but not fully 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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world). The description adds domain behavior beyond annotations by noting that the explanation includes live tier thresholds and that matches are recorded immutably, which helps the agent understand what content the tool produces.

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

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

The description is three sentences, front-loaded with the core purpose, then content details, then usage guidance. Every sentence adds distinct value with no redundancy.

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

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

With an output schema present and annotations covering safety, the description focuses appropriately on what the tool explains and when to use it. The main gap is the unexplained vertical_id parameter, but for a simple read-only explain tool the definition is otherwise complete.

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

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

The single parameter vertical_id has 0% schema description coverage, so the description must compensate but does not mention the parameter at all. The enum values hint at meaning, but the description adds no guidance on how vertical_id selects or filters the explanation.

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

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

The description states a specific verb and resource ('Explains how PreShiftIQ computes matches') and details the content covered: disqualification, measured-fit scoring, immutability, tier thresholds, and the fit-index note. This clearly distinguishes it from retrieval tools like my_matches or broad overview tools like describe_platform, though no sibling is named 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?

It provides an explicit trigger: 'Use this when a user asks how matches are computed or what a match score means.' That is clear context for invocation, but it does not list when not to use it or name alternative tools for adjacent questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds one useful behavioral constraint — only 'published' documents are retrievable — which tells the agent non-published ids will fail, but nothing about error behavior or permissions. A 3 is appropriate given annotations carry most of the load.

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 zero filler that front-loads the operation and enumerates the returned fields. Nothing could be cut 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 needn't document return shape, yet it does so briefly and harmlessly. Combined with the id-provenance hint and the 'published' constraint, an agent has everything needed to call it correctly; only explicit failure behavior is absent.

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

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

Schema description coverage is 0%, but the sole parameter 'id' is given real semantic meaning: it is the identifier returned by the sibling search tool, which tells the agent where to obtain the value. That goes beyond the schema's pattern/length constraints 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 ('Returns one published PreShiftIQ document') plus exactly what it yields (title, text, URL). It implicitly distinguishes itself from the sibling 'search' by tying the input to 'the id search returned', though it doesn't name an explicit alternative tool.

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

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

The phrase 'by the id search returned' establishes the workflow context in which this tool is used, making the search-then-fetch sequence clear. There are no when-not-use conditions or explicit exclusions, but for a single-purpose lookup tool the context is adequately conveyed.

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, closed-world, non-destructive behavior, so the safety profile is covered. The description adds real context beyond that: results are alphabetical, they are coverage-only with no participation status, and the response includes an assessment-start URL.

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

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

Three sentences, front-loaded with what the tool returns and its scope, then usage, then return contents. Efficient, though the parenthetical about the client and assessment adds a slightly heavy clause that could be trimmed.

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

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

Covers purpose, scope boundaries, when to use, and a note about returns; an output schema exists so return values need no further explanation. The only gap is that the single parameter is never explained in prose, which is minor given the enumerated values.

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

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

Schema coverage is 0%, so the description carries the burden, yet it only says 'one vertical' without naming vertical_id or explaining how the enum values (tms, eld, etc.) map to verticals. The self-documenting enum partly compensates, making this adequate but not enriching.

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 (lists vendors PreShiftIQ covers in one vertical) and explicitly scopes it as catalog coverage only, contrasting with client-specific matches that come from a completed assessment. An agent can distinguish this from my_matches 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 clear triggering conditions: 'Use this when a user asks which vendors PreShiftIQ covers or whether a named vendor is covered.' It implicitly contrasts with my_matches but never names a sibling tool as the alternative for the other case, so it stops short of explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the useful detail that the content covers "independence" (a business-model topic), but discloses nothing about the response itself, which is acceptable since it is a static content fetch.

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 waste, with the purpose stated first and the triggering condition second. Appropriately sized for a zero-argument content tool.

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

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

For a no-parameter tool that returns static explanatory content, the description supplies everything needed to select and invoke it, and an output schema exists to cover the return value. Only the absence of sibling differentiation keeps it from a 5.

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 clarify. Baseline of 4 applies, and no parameter confusion is possible.

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: it returns content explaining how PreShiftIQ is paid. This is clear, but it largely restates the tool name and title rather than distinguishing itself from informational siblings like describe_platform or explain_matching.

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

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

"Use this when a user asks about cost, fees, or independence" gives explicit trigger conditions with concrete keywords an agent can match against user intent. It stops short of naming alternative tools or stating when NOT to use it, so it isn't a full 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 establish readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context beyond them: counts are 'live' and sourced from 'the live catalog reader, the same one the public site reads,' telling the agent the values are current and externally consistent rather than cached.

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

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

Three short sentences, each carrying distinct information: what is listed, what each item contains and where the data comes from, and when to invoke it. Front-loaded and free of filler.

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

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

With no parameters, an output schema present, and annotations covering the safety profile, the only open questions are purpose, data provenance, and trigger conditions — all addressed. Nothing needed to call the tool 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?

The tool takes zero parameters, so the baseline of 4 applies. There is no argument semantics to explain, and the description correctly focuses on output content instead of inventing parameter guidance.

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

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

States a specific verb and resource ('Lists the technology categories PreShiftIQ covers') and further specifies the payload: vendor count and client-facing page URL. It does not, however, distinguish itself from the overlapping sibling get_public_catalog, which an agent could easily conflate with this tool.

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

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

Gives a clear triggering condition: 'Use this when a user asks what PreShiftIQ covers.' That is actionable context with no ambiguity about the intent that selects this tool. It names no exclusions or alternatives (e.g., when to prefer get_public_catalog or describe_platform), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real behavioral value beyond them by defining the returned states (in_progress, submitted_pending) and the conditions that produce each, including the resume URL case. It stops short of describing refresh/timing behavior for queued deliveries.

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

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

The description is front-loaded with the primary case and each subsequent sentence earns its place by defining a distinct status branch. The opening sentence is dense with four parallel clauses, which slightly taxes readability but carries 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 the description need not document return values, yet it still explains every status value and the edge case where no assessment has been submitted. Combined with the routing note to my_matches, an agent has everything needed to call and interpret this zero-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?

The tool takes zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to disambiguate. No misleading parameter guidance is present.

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 resource (the signed-in evaluating company's latest PreShiftIQ assessment status) and enumerates exactly what it reports: result availability, review state, notified/accepted/queued match counts. It explicitly distinguishes itself from my_matches, 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?

It gives an explicit exclusion and routing rule: 'Status only; the match list is my_matches,' which tells the agent when to switch tools. It does not, however, address the neighboring status tool my_scorecard_status or state prerequisites such as whether an assessment must exist first.

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 is covered. The description adds meaningful behavioral context beyond that: the caller must be an authenticated advisor, a disclosure must be accepted or the client is only counted as 'withheld', and match cards are masked exactly as the client sees them.

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 required caller identity and scoped tightly to the subject matter, with no filler. It is a single dense, heavily-nested sentence, so the edge-case clauses (withheld clients, masking) are harder to scan than a short bulleted form would be.

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 further explanation, and the description still covers access requirements, entry contents, the withheld-client edge case and the mask-once-matches-exist condition. Nothing an agent needs to call this zero-parameter read tool 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify, and it correctly spends no words on parameter syntax.

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

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

States a specific resource (the assessments of clients the firm represents) with named scope (signed-in consultant or PE firm member) and enumerates exactly what each entry contains (status, Tier 1/2 completion, matches awaiting release, masked match cards). An agent can distinguish this from my_assessment_status and my_matches without opening any schema.

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

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

Clear audience gating ('For a signed-in consultant or private equity firm member') and a precondition ('Available once the consultant disclosure is open') tell the agent when this tool is callable. It does not name a sibling as an alternative, so the routing against other 'my_*' tools 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?

Beyond the readOnly/idempotent/closed-world annotations, the description discloses substantial behavioral rules: masking of cards, review-account behavior with no vendor contact, and the exact conditions under which a vendor's contact details, credits and certification statuses are revealed. It also explicitly states that no pricing is returned, which prevents a wrong assumption about payload content.

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 main retrieval behavior and ordering are front-loaded, and the remaining sentences each add a distinct rule (review accounts, contact disclosure, no pricing). It is dense and slightly run-on, but no sentence is filler.

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

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

With an output schema present, return-value structure need not be documented, and the description instead supplies the semantics an agent needs: default scope, ordering, masking, and the disclosure conditions. Nothing required to call or interpret the tool 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 0% for the single optional parameter, so the description carries the burden and does so: it explains that assessment_id selects a specific assessment and that omitting it falls back to the latest completed one. It stops short of specifying the UUID format or error behavior for an invalid id.

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

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

The description names a specific resource and scope: the notified matches of the latest completed assessment, or of the assessment named by assessment_id, ordered best score first. It is clearly distinct from siblings like my_clients or my_scorecard_status, though it never explicitly contrasts itself with them.

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

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

It states the default behavior (latest completed assessment) and the condition that changes it (assessment_id supplied), which implies when the parameter applies. However, it names no alternative tool and gives no when-not-to-use guidance, so usage is inferred rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine behavioral context beyond them: the conditional disclosure that client contact/company details are exposed only after a lead is accepted, and account-type-dependent output. It stops short of mentioning auth scopes or rate limits, but the gating rule is the significant behavior an agent 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 sentences, front-loaded with the primary vendor summary before the conditional match_id behavior and the client-account caveat. Dense but every clause carries distinct information; only minor tightening is possible.

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 structure need not be restated. The description covers the vendor vs client account split, the meaning of the optional match_id, and the acceptance gate — everything needed to invoke it correctly for a single-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 description coverage is 0%, so the description must carry match_id's meaning, and it does: supplying match_id switches the result to the client contact details and company profile for that lead, subject to the accepted-lead gate. It could still clarify format/validation, but the semantic role of the parameter is clear.

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

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

The description names the exact audience ('the signed-in vendor') and the resource returned (scorecard status/completion plus lead counts broken out as pending, accepted, declined, expiring soon). It also explicitly demarcates the sibling tool my_assessment_status for client accounts, so an agent can 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?

It states the condition for the optional parameter ('with match_id, the contact details...') and the gating rule ('present only once the lead is accepted'). It also gives explicit alternative routing: on a client account a client's matches are under my_assessment_status.

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 behavior: results are returned by id in a fixed order and are explicitly unranked, which materially changes how an agent should interpret and present results. It omits rate limits, result caps, and auth requirements, 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?

Two tight sentences, front-loaded with the verb and corpus, then the return/ordering behavior. Every clause carries information; nothing is redundant with 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile; the description still adds the corpus and the unranked/fixed-order behavior. The only real gap is query-matching semantics, which is the one thing an agent most needs for this 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?

The single 'query' parameter has 0% schema description coverage; the schema only supplies syntactic constraints (pattern, minLength 1, maxLength 200). The description does not explain matching semantics — keyword vs phrase, exact vs fuzzy, case sensitivity — which is exactly what an agent needs to formulate a query for a search tool.

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 ('Searches') plus the exact corpus covered (platform description, published answers per category, vendor catalog), which is far more precise than a bare 'search'. It implicitly separates itself from siblings like get_public_catalog or describe_platform by enumerating the corpus, but never names an alternative, so it stops short of full sibling differentiation.

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 describes what is searched but gives no when-to-use guidance, no exclusions, and no comparison to fetch, get_public_catalog, or describe_platform, which also surface published content. An agent must infer from the corpus alone whether keyword search or a direct fetch is the right call.

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, so the safety profile is covered. The description adds genuinely useful context beyond them: the return value is a URL the user must open, and the tool may interactively prompt for a category — a non-obvious behavior for an otherwise stateless read.

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 primary effect (returns the URL). The middle sentence ("the URL is opened by the user; this tool writes nothing itself") is slightly redundant with readOnlyHint but still short and non-repetitive overall.

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 correctly frames the interplay between the tool and the human (URL opened by user, category prompt). The remaining hole is parameter coverage — the unexplained handle parameter leaves an agent unsure how 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 description coverage is 0%, so the description carries the full burden, yet it never names either parameter. It gestures at "a chosen technology category" (mapping loosely to vertical_id) but gives no hint about the handle parameter, its required format, or that vertical_id is optional with a fixed enum.

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 ("Returns the URL ... to start their operational assessment") and clarifies the scope (URL generation, not a write). It does not name or differentiate against siblings such as my_assessment_status or fetch, so an agent must infer the boundary rather than being told 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?

Usage is implied (call this when the client needs to begin an assessment) and one edge case is handled explicitly: "If no category is given, the tool asks the user to choose one." There is no guidance on when to prefer a sibling like my_assessment_status or describe_platform, and no stated prerequisites.

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