PreShiftIQ

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds business context (payment-blind engine, immutability, buyers pay nothing) that helps an agent explain the platform, but doesn't describe response format or latency.

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

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

Front-loads the platform identity and matching model, then usage and return. A few clauses are dense but each earns its place; 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?

Given a no-param read-only tool with an output schema and full annotation coverage, the description is complete enough: it explains purpose, when to use, and the return. The only minor gap is not contrasting with the closest sibling, explain_matching.

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 is 4. The description correctly implies no inputs are needed and notes the return (platform description plus assessment URL), though the output schema already covers that.

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

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

States exactly what the tool does: explains the PreShiftIQ platform, its matching model, covered categories, and that it is not a directory. Clear verb+resource, and distinguishes itself from siblings like get_public_catalog and 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?

Explicitly says 'Use this first when a user is evaluating, comparing, or selecting technology in those categories,' giving clear when-to-use guidance. It doesn't compare against the sibling explain_matching or list_verticals alternatives, keeping it at 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 already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds valuable domain context (payment-blind engine, immutable match recording, live tier thresholds) which goes beyond annotations. However, it doesn't describe the response shape despite having an output schema, which is acceptable. A 3 is appropriate because annotations carry the behavioral burden and the description's additions are mostly domain flavor rather than invocation-critical behavior.

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

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

Two sentences, front-loaded with the core mechanic explanation followed by precise usage guidance. No filler or repetition; every clause adds substance.

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

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

For a read-only informational tool with full annotation coverage and an output schema, the description is nearly complete. It covers what is explained and when to use it. The only missing piece is guidance on the vertical_id parameter, but with an output schema and rich annotations, the definition is sufficient 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?

The single optional parameter vertical_id has 0% schema description coverage, meaning the schema provides no explanation of what the enum values mean or that the parameter is optional. The description doesn't mention vertical_id at all. However, with one parameter and zero required parameters, the baseline is 4. The description could have explained that omitting vertical_id gives general matching info, but this is a minor gap.

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

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

Specific verb (explains) plus the precise resource (how PreShiftIQ computes matches), naming the exact mechanics covered: disqualification, measured-fit scoring, payment-blind engine, immutable records. Clearly distinguishable from siblings like my_matches (which returns matches) and describe_platform (general platform info).

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: 'Use this when a user asks how matches are computed or what a match score means.' This directly routes the agent away from siblings that fetch actual match data. No ambiguity about when to pick 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 readOnly, idempotent, non-destructive, closed-world. The description adds context annotations cannot convey: results are alphabetical, catalog coverage only, carry no participation status, and are produced by a payment-blind engine. It does not mention pagination or roster size limits, which keeps it from a 5.

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

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

Three front-loaded sentences that lead with what the tool returns. Mild redundancy: 'as catalog coverage only' and 'It is catalog coverage, not a ranking' restate the same exclusion twice, costing a little space.

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

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

A read-only one-parameter lookup with a rich annotation set and an output schema. The description covers what it returns (roster plus assessment-start URL), what it excludes, and when to call it, leaving no material gap for an agent.

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

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

Schema description coverage is 0%, but the single parameter is an enum that already enumerates the five accepted verticals. The description says 'one vertical' but adds no syntax, default, or value guidance beyond the enum, so it neither compensates for the coverage gap nor detracts.

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 vendors PreShiftIQ covers in one vertical') with the scope modifier 'alphabetically, as catalog coverage only.' Clearly separable from siblings like my_matches and list_verticals 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 an explicit trigger ('Use this when a user asks which vendors PreShiftIQ covers or whether a named vendor is covered') and implicitly excludes match/ranking questions by pointing to the buyer's own assessment for matches. No sibling is named as a formal alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable domain context by specifying the exact content of the answer—a buyer-pays-nothing model and vendor independence in matching—which goes beyond the simple title. However, it does not mention that the tool returns a fixed message or that the same response always applies, though that is implied by the context.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then specifies the usage trigger. Every clause is informative and directly relevant, 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?

Given that the tool has no parameters, annotations that fully describe safety, and an existing output schema, the description provides everything an agent needs to decide when to call it: the exact information it returns and the user intent that triggers it. No critical details are omitted.

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

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

With zero parameters, the baseline is 4. The description correctly implies no inputs are required and does not introduce any confusing parameter-related language, so it meets expectations for this dimension without needing to compensate for a schema gap.

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

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

The description uses a clear verb ('States') and resource ('how PreShiftIQ is paid'), and it distinguishes its scope by specifying what the answer covers (buyers pay nothing, vendor payments excluded from matching). This is distinct from siblings like explain_matching and describe_platform because it focuses on the payment model rather than the matching mechanism or platform overview.

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 states when to use the tool: 'when a user asks about cost, fees, or independence.' No alternatives are needed for this zero-parameter informational tool, and the trigger condition is clear and unambiguous.

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 openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: counts reflect the live catalog reader, the same source the public site reads, telling the agent the data is fresh and externally consistent.

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, none wasted: the first states the return shape, the second establishes data provenance, the third states the trigger. 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?

An output schema exists, so return-value detail is not needed here, and the description still sketches the payload. For a zero-parameter read-only tool with full annotation coverage, nothing an agent needs to call it 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, which is the baseline-4 case. There is nothing for the description to clarify or for the schema to be 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?

Specific verb and resource: it lists PreShiftIQ's covered technology categories and names the returned payload (vendor count plus buyer page URL). The purpose is unambiguous, but it never distinguishes itself from the overlapping sibling get_public_catalog, so sibling differentiation is only implied.

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 routes the agent well for one common intent, but no explicit when-not or named alternative (e.g. get_public_catalog) is offered.

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 the scope ('signed-in buyer', 'latest completed') and the boundary with my_matches, which is useful, but doesn't disclose output shape or edge cases beyond that—appropriate given output schema exists.

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

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

Two tight sentences: the first enumerates the status fields, the second draws the boundary with my_matches. Fully front-loaded, zero 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, the description needn't explain return values, and with zero params the schema-side gaps are minimal. It covers scope, field meaning, and sibling differentiation completely for a status-read 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?

Zero parameters, so baseline is 4. No parameter semantics are needed and none are misleadingly implied.

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

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

Names the specific resource ('latest completed PreShiftIQ assessment') and enumerates exactly what status fields are returned (results availability, review state, notified/accepted/queued counts). It explicitly distinguishes itself from the sibling my_matches by stating 'Status only; the match list is my_matches.'

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?

Clearly scopes to the signed-in buyer and declares its boundary against my_matches, telling the agent which tool to pick for the match list. It stops short of stating when-not-to-use (e.g., before an assessment completes) but the context is clear.

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

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

Annotations confirm read-only, idempotent, non-destructive behavior. Description adds crucial business-logic context: masking rules, contact visibility only upon vendor acceptance, score ordering, and no pricing. This goes well beyond annotations and is highly informative.

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 tightly packed sentences that front-load the core purpose and then add key behavioral details. No waste, 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?

Given the single optional parameter, rich annotations, and an output schema (not shown but present), the description covers purpose, usage, and crucial side-effects (masking, contact visibility, pricing). It's complete enough for an agent to call 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 0%, so description must compensate. It explains that assessment_id selects a specific assessment (default is latest completed), adding meaning beyond the schema's bare type. However, it doesn't clarify format (UUID) or edge cases like invalid IDs.

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 (retrieves), resource (notified matches), and scope (for the signed-in buyer, latest completed or named assessment). Clearly distinguished from siblings like start_assessment or my_assessment_status by focusing on match results.

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?

Implies usage for signed-in buyers retrieving matches. Names the condition for specifying assessment_id ('or of the assessment named by assessment_id'). Doesn't explicitly exclude alternatives or state when not to use, but context is clear.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds the useful conditional that buyer contact is exposed only after lead acceptance. It doesn't discuss auth requirements or rate limits beyond the signed-in framing, but the access-gating detail is real added context.

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

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

Two front-loaded sentences, no filler. The default behavior is stated first, then the optional override, which is the right order for a zero-required-parameter tool.

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

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

An output schema exists so return values needn't be restated, and the description still communicates the key access-gating behavior. Complete enough for a simple read tool; a bit more on when the contact is absent would make it fully airtight.

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% and the input is a single bare uuid with no description, so the description must carry it. It does explain what match_id means and the conditional return behavior, which is exactly the missing semantic — only minor gaps remain (e.g. format expectations).

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: retrieves scorecard status, completion, and lead counts for the signed-in vendor. The optional match_id branch (buyer contact details once accepted) distinguishes it from siblings like my_matches and my_assessment_status.

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?

Clearly scopes the tool to the signed-in vendor and describes both call modes (no match_id = summary, match_id = per-lead contact). It does not explicitly name when to prefer this over my_matches, but the vendor-scoped framing makes the boundary inferable.

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 behavior, and the description is consistent with them while adding real value: it clarifies the URL is opened by the user and the tool writes nothing, plus it discloses the interactive fallback of asking the user to pick a category when none is supplied. It stops short of describing where the URL leads or any auth prerequisites.

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 action and outcome, with no filler. The write-nothing clause is useful but slightly restates the readOnly annotation, keeping it just shy of a 5.

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

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

For a simple, zero-required-parameter tool with an output schema, the description covers the return value, side-effect profile, and the interactive no-category path, so an agent can call it confidently. The only real gap is the undocumented client_class parameter, which is a parameter-level rather than behavioral omission.

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 parameter meaning. It refers abstractly to a "technology category" (mapping loosely to vertical_id with its enum of tms, dock-scheduling, etc.) but never names the parameter, and it says nothing at all about client_class or its default of "other", leaving half the parameters unexplained.

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

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

The description states a specific verb and outcome: it returns a URL the buyer opens to start an assessment for a chosen technology category, and clarifies the tool itself performs no write. This is clearly distinguishable from siblings like list_verticals or my_assessment_status, which do not hand back a launch URL.

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

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

Usage context is implied (use it to kick off an assessment in a given category) and it handles the no-category case by prompting the user. However, it never names an alternative or states when NOT to use it (e.g., versus describe_platform or list_verticals to browse categories first), so the agent must infer routing.

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