Fodda Synthetic Expert Consult

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

The description adds significant behavioral context beyond annotations: polling is free, typical duration is a few minutes, recommended polling interval is 15-30s. These details help the agent manage expectations and behavior. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all align).

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 concise sentences: first defines purpose, second explains input and output, third gives practical polling guidance. No fluff, front-loaded, every sentence earns its place.

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

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

For a polling tool, the description covers all necessary aspects: what triggers it (request_deliverable), what to pass (job_id), what it returns (status and artifact links), how often to poll (15-30s), and cost (free). No output schema needed as the description lists return fields. Complete for the use case.

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% (both parameters described). The description adds value by explicitly linking job_id to request_deliverable's response, which clarifies the parameter's origin. For userId, no extra context is given, but the schema description is sufficient. The tool name also implies the parameter semantics.

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 verb ('Poll') and resource ('deliverable status'), and explicitly ties it to the sibling tool 'request_deliverable' by referencing job_id. It specifies the output (status and artifact links), leaving no ambiguity about what the tool does.

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

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

The description gives clear context on when to use the tool: after request_deliverable, with job_id. It provides polling frequency guidance ('every ~15–30s') and typical duration ('a few minutes'). Although it doesn't explicitly state when NOT to use, the context is sufficient for correct 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?

Discloses behavioral traits beyond annotations: responses may include coverage status, source attribution, and referrals, and mandates third-person platform voice for referrals. Also explains auto-resolution of analyst_id for company-specific executives, adding valuable context not in the schema.

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

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

The description is dense but every sentence adds value; it front-loads the core purpose, then covers usage, parameter relationships, and output expectations in a structured, non-redundant manner.

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 tool without an output schema, it sufficiently describes return elements (coverage status, source attribution, referrals) and covers key usage scenarios (one-off vs multi-turn, company-specific handling), making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds important semantic relationships: how company and analyst_id interact (e.g., 'Nike CMO' auto-resolves) and session_id for multi-turn with lower cost, exceeding the schema descriptions and providing additional 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?

The description clearly states 'Consult a named Synthetic Analyst expert' with a specific verb and resource, and differentiates from 'generic search or standard graph queries,' distinguishing it from sibling tools like search_graph and get_node.

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 clear context on when to use (expert voice, unique methodology, multi-turn with session_id) and explicitly instructs to 'Call list_analysts first to find the right expert ID.' However, it does not explicitly name alternatives or state when not to use this tool beyond the generic search distinction.

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?

Richly discloses behavior beyond annotations: the expert answers in their own voice, multi-turn engagements are supported via session_id, responses may include coverage status/source attribution/referrals, and referrals must be presented in third-person platform voice. This far exceeds the neutral annotation hints and provides no contradiction.

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?

Six sentences are purposeful and front-loaded with the core consult action, followed by distinctiveness, prerequisite, response components, and referral handling. It is slightly longer than strictly necessary because of contextual details like consent and curated knowledge graph, but each sentence earns its place.

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

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

Without an output schema, the description compensates by explaining likely response components (coverage status, source attribution, referrals), session continuation, and the required referral voice. Combined with the rich parameter schema and clear usage guidance, it gives an agent sufficient information to select and invoke the tool 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 input schema already provides detailed descriptions for all five parameters (100% coverage), including session_id and analyst_id nuances. The main description adds little beyond reinforcing 'call list_analysts first' and continuing via session_id, so it meets the baseline expected 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 clearly states the tool consults an authorized Human Agent (Digital Twin) expert, with a specific verb ('Consult') and resource. It distinguishes the expert's unique methodology and analytical lens from generic search or standard graph queries, though it could more explicitly contrast with the sibling 'consult_analyst' 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 description tells the agent to call list_analysts first to find the right expert ID, and frames the tool as distinct from generic search or standard graph queries, implying when it should be used. It lacks explicit 'when not to use' guidance or named alternatives beyond list_analysts.

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 and idempotentHint=true, indicating no side effects. The description adds value by stating 'Returns a branded SVG that renders directly in the chat,' clarifying the output format and immediate chat integration, which is beyond annotation scope.

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 two sentences, front-loaded with the purpose, followed by compact chart-type listing and output note. Every sentence adds value without 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?

The description covers purpose, input format, and output (SVG). For a tool with no output schema, this is sufficient. It lacks potential edge-case guidance (e.g., data validation) but is complete for typical use.

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%, with detailed descriptions for both parameters. The description lists chart types in prose but does not add substantial new meaning about parameter structure beyond the schema. Thus, it meets the baseline for high 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 clearly states 'Create a presentation-ready data visualization from research findings,' specifying the verb and resource. It lists six distinct chart types, making the tool's purpose unambiguous and differentiating it from sibling tools.

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 does not explicitly guide when to use this tool versus alternatives like 'request_deliverable.' While it lists chart types, it lacks instructions on choosing among them. Usage context is implied but not explicitly contrasted with siblings.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns capabilities and costs, which is useful but not extensive. No contradictions.

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 two sentences: first states what it returns, second says when to call. Efficient, front-loaded, and no unnecessary words.

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

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

The tool has low complexity (one optional param, no output schema). The description explains the return content (capabilities and costs) adequately. It covers the breadth of what the tool offers, though 'costs' could be elaborated. Still sufficient for the simplicity.

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 input schema has one optional parameter (userId) with description 'Optional user identifier.' Schema coverage is 100%, so baseline is 3. The description does not add any additional semantics about the parameter or how it affects results.

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 returns 'Fodda's main capabilities / features / offerings / products / services / tools and what they cost.' It also specifies when to call it: 'for any question about what Fodda can do or what's available.' This is specific and distinct from sibling tools like get_my_account or list_analysts.

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 explicitly says to call this tool 'for any question about what Fodda can do or what's available.' It provides clear context for when to use it, though it doesn't explicitly state when not to use it or list alternatives. The sibling tool list helps differentiate.

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

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

Annotations already declare the tool read-only and safe. The description adds valuable behavioral context: the exact fields returned (source URL, location, brand names, publication date, category, formatted citation) and the cost per lookup. This goes beyond the annotations and gives the agent a fuller picture of the tool's 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?

Every sentence in the description serves a purpose: what it does, what the output contains, when to use it, what it is not, and cost. It's front-loaded with the core purpose and avoids filler. Perfectly sized for quick comprehension.

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 lookup tool with good annotations and full schema coverage, it's quite complete. It explains the output items, pricing, and usage sequence. It doesn't describe the exact return envelope (e.g., array vs object) or pagination, but the schema covers top_k. Overall, sufficient for an agent to invoke correctly, though a bit more detail on response shape would make it fully 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 description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by clarifying that for_node_id is a 'trend ID' from a prior search_graph result (reinforced in schema) and that the tool is not a text search. This adds contextual meaning beyond the raw schema properties.

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's function with a specific verb ('Get') and resource ('source articles, case studies, and statistics'), and explicitly distinguishes it from text search by saying 'direct lookup by trend ID — not a text search tool.' It also positions it relative to search_graph, making its purpose unmistakable.

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 usage guidance: 'Use after search_graph when you need the supporting proof behind a trend.' It also tells when not to use it ('not a text search tool'), and the pricing hint ($0.50 per lookup) implies a cost consideration. This is clear and actionable.

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 and idempotentHint, so the description adds value by stating that it returns a 'full deterministic list' for trends, implying exhaustiveness and completeness. 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?

Three sentences front-load the core purpose, followed by examples and a specific use case. No wasteful words; each sentence earns its place.

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

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

No output schema, but description implies a list of values. It covers the main intent and differentiates from search_graph. However, it does not specify return format or structure, which could be useful for complex label types.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context for the 'label' parameter with examples and special case for 'Trend', and implies the nature of 'graphId'. Does not significantly enhance 'userId' or 'property' beyond 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?

Description clearly states it lists all values for specific label types (brands, locations, etc.) within a knowledge graph, with concrete examples. It distinguishes from siblings like search_graph by noting that this tool returns a full deterministic list for trends, whereas search may return partial 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?

Provides clear examples of when to use the tool ('explore what a graph contains') and a specific recommendation for trend labels. It implies differentiation from search_graph but does not explicitly list exclusions or alternatives among siblings.

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 specify readOnlyHint=true and idempotentHint=true. Description adds value by stating 'Returns live data — not cached from session start,' which is a behavioral detail beyond annotations. No contradictions.

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, each purposeful: first defines purpose, second gives usage cues, third adds transparency. No redundancy or superfluous text.

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 tool with no output schema, the description sufficiently covers what the tool does, when to use it, and what it returns. Complete in its context.

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?

No parameters, so schema coverage is 100%. Description adds value by enumerating the output fields (balance, plan, graphs, profile), which compensates for the lack of an output 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?

Clearly states the tool checks the current user's account status, listing specific data points (balance, plan, graphs, profile). Distinguishes from siblings like get_capabilities and get_evidence by focusing on the user's own account.

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 example queries to guide usage ('how many API calls do I have?'). Lacks explicit exclusions or alternatives, but the context is clear enough for an agent to select this tool appropriately.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds behavioral details: returns curated editorial links, traversal depth limits (default 1, max 2), requirement for valid node IDs. No contradictions.

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 concise, front-loaded sentences. Every sentence adds value: purpose, elaboration, usage context. No fluff.

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 7 parameters fully described in schema and no output schema, the description covers usage context, prerequisites, and high-level behavior adequately. Could mention output format, but schema coverage compensates.

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?

All 7 parameters are described in the schema. The description adds contextual warnings about not guessing node IDs and the need to call search_graph first, which adds meaning beyond 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 clearly states what the tool does: discover connections (brands, technologies, etc.) to a specific trend. It distinguishes from search_graph by emphasizing curated editorial links not found via web 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?

Explicitly states when to use: after search_graph to map territory, find brands, understand cross-domain relationships. Notes prerequisite (node_id from search_graph). Lacks explicit 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by listing the specific fields returned (description, lifecycle stage, signal strength, geographic scope, all properties), which goes beyond the annotations. No contradictions.

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 two sentences: the first states the purpose and output, the second provides usage guidance. It is concise, front-loaded, and wastes no words while conveying all essential 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?

Given the tool has 3 parameters, no output schema, and annotations present, the description covers the main points: what it returns, when to use it, and required inputs. It does not explain the exact output structure or error conditions, but the listed fields provide a sufficient overview. Annotations already address safety and idempotency.

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% with detailed descriptions for each parameter, especially nodeId (with warning against guessing) and graphId (with examples). The description reiterates the need for node_id but does not add significant new semantics beyond what the schema already provides. Baseline of 3 is appropriate when schema is thorough.

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 retrieves the full profile of a specific trend, including detailed description, lifecycle stage, signal strength, geographic scope, and all properties. It explicitly distinguishes from sibling search_graph by noting that this tool provides deeper detail on a single trend after a summary.

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 explicitly states when to use ('when you need deeper detail on a single trend after search_graph returned a summary') and the prerequisite (requires node_id from a prior search_graph result). It does not explicitly mention when not to use or alternative tools beyond search_graph, but the guidance is clear and actionable.

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, covering the safety profile. The description adds meaningful context beyond annotations by specifying that the tool lists both human agents and synthetic analysts, clarifying the scope of outputs. It does not describe return format or pagination, but the annotation coverage lowers the burden.

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

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

The description is two sentences, front-loaded with the primary purpose in the first sentence. The second sentence adds usage guidance without redundancy. Every phrase earns its place, making it highly concise and well-structured.

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 list tool with one optional parameter and no output schema, the description adequately covers the tool's function and distinguishes it from querying. It gives enough context for an agent to select and invoke the tool correctly, including examples of expected content.

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 input schema has one optional parameter 'userId' with a description, giving 100% schema coverage. The tool description does not mention this parameter, but the schema fully documents it. Per the baseline, with high schema coverage the description need not add parameter details, so a 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 uses a specific verb 'Lists' and clearly identifies the resource: available human agents and synthetic analysts. It provides concrete examples (e.g., brand-cmo, brand-ceo, Anu Lingala), which disambiguates the tool from siblings like consult_analyst. The purpose 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?

The description explicitly tells when to use this tool (to list analysts) and when not to: 'To query a company-specific synthetic expert... consult brand-cmo' implies using a different tool (likely consult_analyst). It gives a clear alternative path, though it does not name the sibling tool directly, which prevents 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return content (IDs, descriptions, authors, sectors, signal counts, topic coverage) and its role as a prerequisite, but does not elaborate on pagination or error 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?

Three concise sentences, front-loaded with the action and output, then usage guidance. No redundancies; every sentence earns its place.

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

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

For a simple read-only list tool with rich annotations and a fully described schema, the description clearly states what it does, when to use it, and what it returns. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

The schema covers the only parameter (userId) with a full description, achieving 100% coverage. The description does not add anything about parameters, but the schema does the heavy lifting, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('List'), identifies the resource ('expert knowledge graphs'), and defines scope ('the user can access'). It also enumerates the returned attributes (IDs, descriptions, authors, sectors, signal counts, topic coverage), distinguishing it from sibling tools like search_graph and get_node.

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 instructs to 'Use FIRST in any session to discover available sources before searching', providing clear timing and implying precedence over search tools. It also notes the metadata is needed for graphId parameters in other tools, reinforcing its role as a prerequisite.

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=false, destructiveHint=false), the description adds significant behavioral context: the analyst researches in the background, the offering price is charged on acceptance, and research is included in the price. This is crucial for an agent to understand the financial and async implications of the call.

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 efficiently front-loaded with the purpose, followed by actionable steps, async behavior, pricing, and a concrete example. Every sentence serves a purpose; no fluff or repetition.

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

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

For an async, stateful tool with no output schema, the description explains the full lifecycle: commission, background research, job_id return, polling with check_deliverable_status, and artifact links. It also mentions pricing and example brief, covering all necessary operational aspects.

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 100% schema coverage, the description is not required to re-explain parameters, but it adds value by giving an example brief ('Marketing plan for a DTC skincare launch...') and clarifying that offering_key comes from the analyst's offerings list. This goes beyond the schema's field descriptions without redundancy.

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 action ('Commission a finished document from an analyst') and clarifies the resource (skill-based deliverables like marketing plans, deck reviews, trend briefings). This clearly distinguishes it from sibling tools such as check_deliverable_status (polling) and consult_analyst (interactive consultation).

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 concrete usage context: specify offering_key from list_analysts, provide a 2–5 sentence brief, optional attachments, and expect an asynchronous job with polling via check_deliverable_status. It does not explicitly state when not to use this tool or name alternatives, but the workflow is clear enough for correct 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 declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable behavioral context: parallel search across all accessible graphs when graphId is omitted, output includes cited evidence and lifecycle stage, and a price of $20 per query. These details go beyond the annotations and set correct expectations without contradiction.

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: purpose, output highlights, and usage/pricing. It is front-loaded with the core function, contains no fluff, and every sentence adds substantive information. This is concise and well-structured.

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 8 parameters and no output schema, the description covers key aspects: what the tool searches, what results look like (cited evidence, source attribution, lifecycle stage), default behavior, and cost. It does not mention ranking or result ordering, but for a search tool this is adequately complete. Sibling tools like get_evidence and get_node clarify the ecosystem, so the description is sufficient.

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%, meaning every parameter already has a clear description. The main description re-states the graphId default behavior ('If graphId is omitted, searches ALL accessible graphs in parallel') but adds no new syntax or format details beyond that. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds marginal value.

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's purpose with a specific verb+resource: 'Find trends, signals, and expert insights across 100+ curated knowledge graphs.' It also distinguishes from web search by saying 'not generic web summaries' and from sibling graph tools by focusing on cross-graph search rather than node/edge access. This makes the tool's role 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?

The description provides explicit use cases: 'Use for market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts, or any topic where curated expert intelligence outperforms web search.' It also gives default behavior guidance for graphId. However, it does not explicitly state when not to use this tool or mention alternative sibling tools, so it falls just 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.