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

Beyond the readOnly/idempotent annotations, the description discloses that the list may be empty, reveals the exact return object shape, explains the semantics of toolsets and knowledge, and warns that names/descriptions can be misleading. This is rich behavioral context that helps the agent interpret results correctly.

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 longer than typical, but every section earns its place: purpose, return structure, field semantics, routing guidance, and empty-list caveat. The use of bullets and bolded field names keeps it scannable and front-loaded with the core purpose.

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

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

Despite having no output schema, the description fully compensates by detailing the return object, nested structures, and field meanings. It also covers edge cases (empty list, misleading names) and alternatives, making it complete for an agent to invoke and interpret correctly.

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

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

The schema already fully documents the single search parameter with 100% coverage, including case-insensitivity, substring matching, and omit behavior. The description adds no further parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List the PipesHub agents configured for this org, each with its capabilities.' It also clearly differentiates this tool from siblings like pipeshub_chat by explaining that this is for listing agents, not conversing 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?

The description gives explicit routing instructions: use this tool to discover agents, take the agentId, and pass it to pipeshub_chat; for plain Q&A use pipeshub_chat without agentId. It also states when to refrain from forcing an unrelated agent, providing clear when-to-use and when-not-to-use 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?

The description discloses critical behavioral traits beyond the annotations: it reads only a few retrieved passages, never a whole document or complete list; it undercounts exhaustive queries and won't say so; conversation lifecycle behavior (omit conversationId on first turn, pass it on follow-ups, filters ignored on follow-ups); and how to download cited documents. The annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, and the description adds substantial context about what the tool does and doesn't do. No contradiction with annotations.

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

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

The description is long but every section earns its place: the three-wrong-questions list, the mode explanations, the conversation lifecycle, and the citation download pointer. It's well-structured with bold headers and bullet-like formatting. It could be slightly more concise, but the density of actionable information justifies the length. The most critical routing information is front-loaded.

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

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

For a complex tool with 8 parameters, nested objects, no output schema, and multiple modes, the description is remarkably complete. It covers the three modes (internal_search, web_search, agent chat), the conversation lifecycle, the filters scoping, the citation download flow, and the routing to siblings. The only minor gap is that it doesn't describe the exact response format beyond 'answer plus citations', but the description explicitly tells the agent how to use citations, which is what matters for follow-up actions. No output schema exists, so the description carries the burden, and it does so thoroughly.

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 75%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the conversation lifecycle (omit conversationId on first turn, pass it on follow-ups, filters ignored on follow-ups), the chatMode semantics (internal_search vs web_search vs quick with agentId), and the filters behavior (only meaningful on first turn, apps ids from pipeshub_sources). This is valuable semantic context that the schema alone doesn't provide. The description doesn't cover modelKey/modelName/modelFriendlyName, but those are self-explanatory and the schema covers them.

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

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

The description opens with a specific verb and resource: 'Ask a question, get an answer grounded in the org's indexed data with citations.' It immediately distinguishes itself from siblings by naming the three question types it gets wrong and routing them to pipeshub_get_record_content and pipeshub_search. This is a clear, specific purpose statement that differentiates the tool from its siblings.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It lists three categories of questions the tool gets wrong and directs the agent to the correct alternative for each. It also gives concrete examples ('What's our policy on Y?' → pipeshub_chat internal_search; 'Find / locate the file named X' → pipeshub_search). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: whoami errors if the credential is expired/revoked, and output shape varies by action. It also notes that whoami is 'confirmed against the server', implying a network round-trip. These are useful, non-obvious details that help an agent understand side effects and failure modes. No contradiction with annotations.

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

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

The description is well-organized: a one-line purpose, then a bullet list of actions with their unique characteristics. It front-loads the main intent and uses formatting to make scanning easy. Every sentence earns its place – no filler or redundancy. The length is appropriate for a multi-action 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?

Given the tool is read-only with five actions and a fully self-describing schema, the description covers the essential information: each action's purpose, when to use it, required vs optional parameters, and the nature of the output (e.g., userCount, capability flags). It could mention default pagination values or what happens on empty results, but those are minor gaps. No output schema exists, so the description must convey output variability – it does. Overall, an agent can correctly invoke this tool based on the description alone.

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

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

Schema description coverage is 100% – every parameter (action, page, limit, search, userId) has a description in the schema. The description essentially mirrors the schema content, re-stating what each action does and its parameters. Since the schema already carries the full burden, the description adds little new meaning. Baseline 3 is appropriate; it doesn't hurt but doesn't enhance.

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 opens with 'Look up people, groups, and teams in PipesHub' – a specific verb, resource, and domain. It enumerates five distinct actions (whoami, list_users, get_user, list_groups, list_my_teams) and describes what each returns, making it immediately distinguishable from sibling tools like pipeshub_search or pipeshub_get_record_content. No ambiguity remains about what the tool is for.

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

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

The description gives explicit per-action usage guidance: it tells you to use whoami when you need the caller's identity, and even notes to use it before get_user on yourself. It lists prerequisites for get_user (userId) and states that list_* actions use pagination. However, it doesn't explicitly contrast this tool with siblings (e.g., 'for full-text search use pipeshub_search'), so it's not perfect, but it's clear enough for an agent to choose the correct action within the 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 this as a safe, idempotent read (`readOnlyHint: true`, `idempotentHint: true`, `destructiveHint: false`), lowering the burden on the description. The description adds useful behavioral detail beyond annotations: it explains that the Content-Type is forwarded from upstream, binary content is base64-encoded, and text content is inline. This gives the agent realistic expectations about the response without contradicting the annotations.

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

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

The description is compact and front-loaded with the core action. The bullet-style source examples are easy to scan Bernstein and the final sentence clearly conveys response encoding without redundancy. No sentence is wasted, and the structure helps an agent quickly extract the key facts.

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 two parameters, one required, and no output schema, the description covers the essential call details: where to get `recordId`, what the response is like, and how content is encoded. The main miss is the lack of guidance about how this tool relates to `pipeshub_get_record_content`, which prevents the context from being fully complete for tool selection.

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?

Input schema coverage is 100%, so the schema already documents both parameters well. The description adds examples of where `recordId` comes from, but these examples also appear in the schema's parameter description. It does not meaningfully extend parameter understanding, particularly for `convertTo`, which is only described in the schema. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a clear verb and resource: 'Stream the binary content of a single record from PipesHub.' The title 'Download a document by record id' reinforces the operation. However, it does not explicitly contrast with the sibling `pipeshub_get_record_content`, so an agent may not be able to distinguish the two tools solely from this description.

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 provides useful context for the `recordId` parameter by pointing to chat citations and search results, which helps an agent know where to obtain the input. It does not, however, say when to prefer this tool over alternatives such as `pipeshub_get_record_content`, nor does it state exclusions or conditions for use. The usage guidance is therefore implied rather than explicit.

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

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

Beyond annotations (readOnlyHint=true), the description discloses return formats, edge cases ('No record found', '200 with empty matches', 'ambiguous' handling), resolution behavior ('searches ALL connectors'), pagination triggers ('only pass page:2 when Next: line says more'), and rendering details. No contradiction with annotations.

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

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

The description is lengthy but every sentence adds practical value for a tool with three modes and 13 parameters. It is front-loaded with a mode summary, uses clear section headers, and avoids filler. The structure mirrors the decision flow an agent needs.

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

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

For a complex tool with no output schema, the description fully explains return values for all modes, prerequisites (like obtaining recordId), error/edge behaviors, and sibling routing. Nothing an agent needs to invoke correctly is missing, given the rich schema and annotations.

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?

Although schema coverage is 100%, the description adds significant contextual meaning: explains how to obtain nodeId, when to omit it, how depth affects output, how identifiers resolve automatically, and how to interpret returns like 'Children 1-50 of 61'. These are usage patterns beyond schema field definitions.

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 clearly states the tool performs three operations (lookup, navigate, content) on the org's records, with each mode named and explained. It explicitly differentiates from siblings (pipeshub_chat cannot see whole docs, pipeshub_download_record for raw bytes), making purpose 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?

Provides explicit when-to-use guidance per mode, including intent-based examples ('what's this doc about?' → content) and exclusions ('Use pipeshub_download_record only for the original file bytes', 'pipeshub_chat cannot do these'). Also tells when to pass depth and how to get recordId, leaving no ambiguity about selection.

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

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

Despite annotations providing idempotentHint and destructiveHint, the description goes much further: it discloses that results are 'a ranked sample, never a complete list', that hits are top-scoring blocks rather than all matches, and that counts should not be used for 'how many'/'all'/'every' answers. This is rich behavioral context beyond the annotations.

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

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

The description is long but well-structured with bolded headers and bullets, and every section carries operational value. It is front-loaded with the core purpose before caveats. Some minor redundancy with the schema's query description exists, but the density is justified by the important sampling caveats.

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

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

With no output schema, the description compensates by giving the response row shape, ordering, and the possibility of duplicate recordIds across hits. It also covers result presentation via webUrl and warns against misusing the ranked sample for counts. For a search tool with three parameters, this is complete.

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

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

Schema coverage is 100% and each parameter already has a meaningful schema description, so the baseline is 3. The description adds extra value by recommending small limit values (5–10) for filename/topic resolution and noting that apps come from pipeshub_sources, which helps agents choose parameters more effectively.

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 opens with a specific verb and resource: 'Vector / semantic search across the org's indexed documents', and clarifies the tool's primary purpose: LOCATE a document and resolve it to a recordId. It explicitly differentiates from pipeshub_chat and pipeshub_get_record_content, so an agent can distinguish it from siblings.

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

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

The description gives explicit when-to-use guidance ('Use this when the user wants to LOCATE a document') and when-not-to-use guidance ('Not for structural questions'), naming pipeshub_chat and pipeshub_get_record_content mode:navigate as alternatives. It also lists typical use cases, leaving no ambiguity about selection.

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

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

Annotations already mark this read-only and idempotent, and the description goes further: it discloses the synthetic knowledgeBase_<orgId> entry, the default sections, the conditional fetching of embeddingModels, and the stable-but-changeable nature of the data. It also says exactly which returned field to pass to which sibling parameter.

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 one-line purpose, uses bulleted sections and code formatting, and every sentence earns its place. The only slight length is justified by the lack of an output schema, so it needs to describe return structure.

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 discovery tool with no output schema, it fully explains the three return sections, the special knowledgeBase source, the exact field-to-parameter mappings, the default selections, and when to request embedding models. Nothing essential is missing for an agent 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 100%; the schema already documents include's enum, default value, and the re-embedding use case. The description reinforces that and adds an isDefault selection hint, but it adds no material parameter meaning beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Discover available chat sources and AI models in one call.' It clearly enumerates the three returned sections and distinguishes this discovery tool from chat/search siblings by explaining that its ids feed pipeshub_chat and pipeshub_search.

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

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

It gives explicit usage timing: 'Call this once at the start of a session and cache the result.' It also explains when include should be varied and how returned values are consumed by sibling tools. It does not explicitly name sibling alternatives to exclude, but the discovery-vs-action separation is clear.

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