Revensi

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely new scope context beyond them: the write is catalog metadata only and confers no account connection or access grant, which prevents a serious misinterpretation of what is being mutated.

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 usage trigger front-loaded and the scope caveat immediately after. Nothing to trim.

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 plus description cover safety and scope. However, for a creation tool with 0% parameter description coverage, the definition leaves the agent to infer what 'category' to pick, which is a real gap 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 0% for both parameters. The description says nothing about the 'name' constraint (1-120 chars) or the meaning/selection criteria for the 'category' enum. The enum values are largely self-explanatory, which keeps this above a 1, but the description does no compensating 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 action on a specific resource: naming an external service in Revensi's connector catalog. This separates it from list_connectors and remove_connector, though it never explicitly says 'create/add an entry' as a verb, relying on the title for that.

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 the user wants to...' gives an explicit trigger condition, and 'This does not connect an account or grant access' rules out a plausible mis-selection. It does not name a sibling alternative, 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 write/idempotent/non-destructive, so the bar is lower; the description adds real value by pinning the lifecycle state (draft only, no publish, no run) and the human-approval gate. It does not explain idempotency/retry semantics beyond what the requestId schema note covers.

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

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

Two short sentences, front-loaded with the gating precondition, and the second sentence delivers the key behavioral boundary. 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 an 11-parameter, deeply nested create tool, the description is thin: it explains intent but nothing about payload structure, required vs optional fields, or what 'complete' means. An output schema exists, so return values are covered, but the input side is largely unexplained.

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

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

Schema description coverage is only 9% (just requestId), with 11 parameters and a deeply nested 'map' object. The description says nothing about origin, name, period, purpose, department, or the required map structure, so it does not compensate for the 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?

States a specific verb and resource ('Creates one draft' of a workflow) and clarifies the lifecycle boundary ('does not publish or run'). It implicitly separates itself from get_workflow/list_workflows, though it never names a sibling to route against.

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 only after the user reviews and approves a complete conversation-drafted workflow' gives a clear precondition and an implied exclusion (unapproved or incomplete drafts). It stops short of naming an alternative tool for the non-approved case.

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 still adds genuinely new facts beyond them: 'No authentication needed' and the explicit non-execution/non-grant boundary. It does not, however, say what happens on a missing or unpublished slug.

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 action, with the caveats trailing. The contents enumeration is slightly listy but each item earns its place by telling the agent what the payload includes; there is 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?

An output schema exists, so return shape need not be described, and annotations carry the safety profile. Given that, the description covers the remaining agent-facing unknowns — auth requirement, scope of contents, and the limits of what the call does — leaving only the sibling ambiguity as a gap.

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

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

The single parameter 'slug' has 0% schema description coverage (only a regex and maxLength, no prose), and the description never mentions it at all — not that it is the agent's unique published identifier, nor what an unpublished/mistyped slug yields. With one undocumented parameter, the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Read the full published blueprint,' and enumerates exactly what that blueprint contains (inputs, outputs, tools, deliverables, evaluations, examples). It is far more informative than the title, but it never distinguishes itself from the nearby sibling get_agent_spec, so an agent still has to guess which of the two returns 'the blueprint'.

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 'read the full published blueprint,' and the description rules out two adjacent capabilities ('does not execute an agent or grant access to external systems'). However, it never says when to pick this over get_agent_spec or search_agents, which are the real competing tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds genuinely new behavioral context: 'No authentication needed' and the negative scope statement that it does not create, connect or run the agent. That is useful disclosure beyond the structured fields, though no mention of rate limits or response shape.

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

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

Three short sentences, purpose front-loaded, each sentence carrying distinct information (what it returns, auth profile, negative scope). 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?

An output schema exists so return values needn't be described, and annotations cover the safety profile. But for a two-param tool with an unexplained enum, the description is not complete enough — an agent knows what it fetches but not how to choose a 'handoff' value.

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% and there are two parameters. The description explains neither 'slug' (how to identify the published agent) nor 'handoff', whose enum values (codex, claude-code, personal-agent) are entirely uninterpreted anywhere. With low coverage the description must compensate and it does 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?

States a specific verb+resource: 'Get a published agent's Markdown build brief.' This distinguishes it from the sibling get_agent by specifying the artifact is a Markdown spec/brief. It falls short of 5 because it doesn't name get_agent or explain how the two differ for an agent deciding between 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?

'to adapt to the user's systems' implies the use case, and 'it does not create, connect or run the agent' helps exclude wrong intent. However, it never names an alternative tool or states explicitly when to prefer get_agent_spec over get_agent, leaving routing 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 and closed-world, so the safety profile is covered. The description adds a genuine scope constraint the annotations cannot express: the interview transcript is deliberately excluded from the result.

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: the usage trigger first, the exclusion second. No restatement of the name, no filler, nothing that fails to earn its place.

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

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

With an output schema present, the return shape need not be enumerated, and the annotations carry the safety semantics. The only residual gap is that the description never clarifies what identifiers are valid beyond the schema's uuid pattern.

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 single workflowId parameter is documented only by its uuid format, not by description text. The obligation to identify which workflow's ID to pass is left entirely to the caller's inference from the surrounding context.

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 pair (retrieve a single saved workflow) and enumerates the payload (map, effort, scores, open questions), which implicitly separates it from list_workflows and list_workflow_questions. It stops short of naming a sibling to route against, so it lands just under the top tier.

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

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

"Use this when the user wants one saved workflow's..." gives an explicit usage trigger, and "Never returns the interview transcript" supplies a negative boundary. It does not, however, point to the alternative tool for transcript or list cases, so the when-not side is only half-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 this a safe, idempotent, closed-world read. The description then adds auth-context that annotations cannot convey: these are catalog records, not authenticated external accounts, which prevents the agent from misinterpreting the results. It says nothing about pagination behavior for the cursor param, keeping it out of 5 territory.

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 invocation trigger, and no wasted filler. It is appropriately sized for a list tool, though the phrasing 'wants named services... and which workflow maps mention them' is slightly convoluted.

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 annotations cover the safety profile. The meaningful gap is pagination and filter semantics: a four-parameter paginated list tool with cursor and query left undefined is under-described 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 0%, so the description must carry the burden for all four parameters, yet it explains none of them. limit, query, and cursor are entirely undocumented, and workflowId is only indirectly gestured at by 'which workflow maps mention them,' which describes output rather than the filter.

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

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

The description identifies a clear resource (named services in the Revensi connector catalog) and even the cross-reference returned (which workflow maps mention them). However it never states an explicit verb like 'list', and it does not distinguish this from siblings such as list_resources or list_workflows, so it falls short of a 5.

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

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

The opening clause 'Use this when the user wants...' gives a concrete trigger condition for invocation, which is better than implied usage. It names no alternatives or exclusions (e.g., add_connector/remove_connector, or when to prefer list_workflows), so it stops short of the explicit when-not guidance required for 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 adds genuinely useful non-structured context: the tool returns metadata only and will not surface document bodies, which sets agent expectations about result 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?

Two short sentences, the usage trigger front-loaded and the important negative constraint second. Every clause earns its place with no filler.

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

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

An output schema exists, so return-value structure need not be explained, and the metadata-only boundary is covered. However, for a paginated list tool the description omits any hint that limit/cursor control paging, which is a meaningful gap 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 schema has 2 parameters with 0% description coverage, so the description carries the full burden and it says nothing about them. Neither the pagination semantics of limit/cursor nor the fact that results are paged is mentioned, leaving the agent to infer pagination behavior from bare property names.

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 concrete action (returning metadata for files) and a concrete scope (the Revensi resource library), so an agent can tell it retrieves resource listings rather than a single resource. It does not explicitly name or contrast with sibling list tools like list_connectors or list_workflows, 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?

"Use this when the user wants metadata for files saved in their Revensi resource library" gives a clear triggering condition, and "Does not return document bodies" implicitly routes body-fetching needs elsewhere. No explicit named alternative or exclusion is given, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious behavior beyond that: results are implicitly scoped to active, non-archived workflows, and the tool is read-only in the sense that it never resolves items. It omits pagination/return behavior, but the output schema covers that.

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 no filler; the usage trigger is front-loaded and the boundary note follows. 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?

Because an output schema exists, return values needn't be described, and the annotations carry the read-only profile. The remaining hole is parameter behavior across seven undocumented params, which the description never addresses, leaving it only minimally adequate for a tool of this parameter 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?

Seven parameters with 0% schema description coverage and the description mentions none of them. Enum value names (open/deferred, blocker/question) partly self-document state and priority, but limit, query, cursor, workflowId, and department are left entirely unexplained in both schema and description, so the description does not compensate for the coverage gap.

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

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

States a specific verb (list) and resource (workflow questions) and narrows scope to unanswered/deferred questions and blockers in active, non-archived workflows. It is clear what it returns, though it never names or contrasts with a sibling such as list_workflows, so the sibling-differentiation credit is partial.

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 opening clause gives an explicit trigger (user wants unanswered or deferred questions and blockers), and the closing sentence supplies a negative boundary ('does not answer them'), steering the agent away from using this for resolution. It stops short of naming the alternative tool to use for answering.

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 behavior, so the safety profile is covered. The description adds a scoping note ("Returns live workspace data, not an interview transcript"), which usefully clarifies the data source, but says nothing about pagination, filtering, or result ordering.

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

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

Two short sentences with the trigger condition front-loaded and no padding. The second sentence is slightly cryptic out of context but still earns its place by clarifying the data source.

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 explained, and annotations cover the safety profile. However, for a 5-parameter filtered-list tool with zero param descriptions, the absence of any guidance on filters or paging leaves real gaps.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden — and it contributes nothing about limit, query, cursor, status, or department. The names and enums are largely self-explanatory, which keeps this above a 1, but pagination semantics for cursor/limit are entirely undocumented.

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 clear verb (find/compare) and resource (saved workflows in the Revensi workspace), and the singular sibling get_workflow is implicitly contrasted by the list semantics. It does not, however, explicitly distinguish itself from siblings like get_workflow or list_workflow_questions.

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 the user wants to find or compare saved workflows" gives a usable trigger condition, which is more than most list tools offer. But it names no alternatives and no exclusions, so an agent must infer when to prefer get_workflow over this.

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, but the description adds real behavioral content beyond them: it refuses entries still referenced by any workflow, does not touch external account connections, and requires an explicit user request. It still doesn't say whether the removal is permanent or how a refusal is surfaced, so not a full 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, zero padding, with the usage gate front-loaded ahead of the behavioral caveats. Every clause carries a distinct 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 a destructive two-parameter tool with an output schema (so returns need no explanation) and destructiveHint annotations, the description covers preconditions, refusal behavior, and scope limits. The main omission is whether successful removal is reversible.

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

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

Schema coverage is 50%: confirmName is documented in the schema while connectorId carries only a UUID format/pattern. The description's 'exact named catalog entry' echoes the confirmName confirmation intent and implies the name must currently exist, which compensates only partially for the undocumented identifier.

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 ('remove the exact named catalog entry') and bounds the scope ('does not disconnect external accounts'), which separates it from remove_resource and from disconnecting accounts. It never names a sibling tool, 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?

'Use this only after the user clearly asks to remove the exact named catalog entry' gives an explicit precondition, and the refusal rule adds a concrete use/abort condition. No alternatives are named (e.g., when to prefer disabling or removing a resource instead), so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful scope detail beyond that: exactly what is destroyed (library copy, searchable chunks) and what residual data survives (historical workflow quotations). It does not state reversibility or permissions, keeping 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?

Two sentences, zero filler, with the confirmation precondition front-loaded before the destructive effect. Every clause carries information the 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?

An output schema exists, so return values need no explanation, and annotations carry the destructive/read-only profile. The description covers the confirmation gate and destruction scope, though it omits whether the deletion is permanent or undoable, which would fully close the loop for an irreversible operation.

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

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

Schema description coverage is 50%: confirmName is documented in-schema, resourceId is not. The phrase 'the exact named resource' reinforces the confirmation parameter's intent but adds no format, source, or lookup guidance for resourceId, so it is only marginally better than the schema.

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

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

The description names a specific verb+resource effect: 'Deletes its library copy and searchable chunks,' which pins down scope more precisely than the title alone. It doesn't explicitly contrast with the sibling remove_connector, but the resource-file scope is unambiguous from the title and text.

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 only after the user confirms the exact named resource' gives a clear, actionable precondition for invocation. It stops short of naming alternatives or stating when a different removal tool (e.g., remove_connector) is appropriate, so it is clear context without 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: no authentication is needed, and the results are static specifications/fictional examples rather than live connected agents, which materially affects how results should be interpreted.

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 what the tool does, followed by the auth condition and the critical data-nature caveat. Every sentence earns its place with no redundancy.

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

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

With an output schema present, return values need not be described, and the description covers purpose, auth, and the fictional/spec-only nature of the data. The remaining gap is pagination behavior (the cursor parameter) and how the enum filters interact, which is minor but real for a 6-parameter search 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 parameter meaning. It names the filter facets (task, department, system, integration), which maps onto query/department/system and partially trigger, but says nothing about limit, cursor/pagination, or the enum values for trigger and department.

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 (search) and resource (published agent blueprints) plus the facets it searches by, which is clearly distinct from the id-based siblings like get_agent and get_agent_spec. It does not explicitly name an alternative, but the verb+resource combination 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?

Implies usage through 'search ... by task, department, system or integration' and notes no account is required, so an agent can infer discovery-style queries. However, it never says when to prefer this over get_agent or get_agent_spec (e.g., 'use when you don't have an agent ID'), leaving the routing to inference.

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