Fodda Deep Research

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, making the tool safe to poll. The description adds essential behavioral context: polling every 10 seconds until COMPLETE or FAILED, which justifies repeated calls.

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 concise sentences front-loaded with purpose and crucial usage instructions. Every sentence adds value with no redundancy.

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

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

For a simple polling tool with one parameter and no output schema, the description sufficiently covers invocation, polling strategy, and termination conditions. Minor omission: does not mention possible error handling or retry logic, but overall complete for the task.

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?

Only one parameter (job_id) with full schema description coverage (100%). The description adds no new semantic value beyond what the schema already provides ('The Job ID returned by deep_research_topic'). Baseline score 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?

Description explicitly states the tool checks if deep research is complete and retrieves the report. It uses a clear verb ('Check') and resource ('deep research status'), and distinguishes itself by referencing the initiating tool and polling behavior.

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

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

Clearly states when to use (after deep_research_topic) and provides polling frequency and termination conditions. Does not explicitly mention alternatives (like check_supplemental_status), but the guidance is sufficient for correct usage.

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 show readOnlyHint and idempotentHint. Description adds polling behavior and expected statuses. No contradictions, but could mention behavior after completion or error handling.

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?

Extremely concise: one purpose sentence plus clear usage directive. No redundant wording.

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 polling tool with one parameter and no output schema, the description covers key aspects: purpose, trigger, polling cycle, and end states. Could mention result format but not critical.

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 job_id description linking to get_supplemental_context. Description reiterates that but adds no new parameter details. Baseline of 3 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?

States specific action ('check if market data gathering is complete and retrieve the results') and distinct resource (supplemental context). Context of use after get_supplemental_context differentiates from siblings like check_research_status.

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

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

Explicitly instructs when to call ('after get_supplemental_context'), how to use (poll every 5-10 seconds), and termination conditions (COMPLETE or FAILED).

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 adds some useful behavioral context beyond the annotations, such as the agent planning its strategy, searching multiple graphs, validating with institutional data, and automatically including earnings-call and macro/supplemental data. However, with sibling tool check_research_status present and no output schema, the description is ambiguous about whether this launches an asynchronous session whose results must later be fetched, which is an important behavioral detail. The annotations already declare this as read-only, so no contradiction results, but the missing async handoff weakens transparency.

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?

This long description is firmly front-loaded with the action and deliverable, followed by use-case guidance and a clear 'don't call other tools' note. Each sentence provides substantive information. It is a bit verbose compared to minimal examples, and the middle strategy sentence could be condensed, but overall the structure and urgency are strong.

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's complexity, the schema covers all parameters well, but the absence of an output schema increases the burden on the description to explain how results are returned. The description says the tool produces a narrative brief but does not state whether this is returned immediately or the caller must later poll check_research_status. That is a material operational gap for a research-launch tool and the exact reason siblings like that exist.

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 (query, mode, depth, userId, graphId, sub_themes) has an explanatory description and constraints. The tool description itself adds one relevant pointer by implicitly warning to put detail in sub_themes rather than query, and by relating that the tool automatically includes context when warranted, but does not significantly explained beyond what the schema already covers. This is appropriately a baseline 3.

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 strong verb, 'Launch an autonomous Deep Research session,' and names the concrete resource it acts on: Fodda knowledge graph intelligence combined with live web research. It clearly states the deliverable ('comprehensive editorial-quality report' with inline citations) and differentiates itself from simpler lookups by stating that earnings and supplemental tools should not be called separately.

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 this tool: 'for complex, multi-faceted questions that need both curated expert intelligence AND current web context,' and provides concrete examples such as strategic briefings and competitive deep dives. It also advises against calling earnings or supplemental tools separately. It does not, however, name specific alternative sibling tools or provide explicit 'do not use when...' guidance for simple questions.

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

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

The annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds useful behavioral context beyond that: it returns a branded SVG that renders directly in chat and supports focus highlighting. This explains the user-visible output and customization behavior 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 dense but well-organized: the core purpose leads, the available chart types are enumerated compactly, and the output format plus focus option are stated in the final sentence. Every sentence contributes necessary decision-making or invocation information without padding.

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 with two required parameters, a complex nested data string, and no output schema, the description covers chart-type choices, data schemas, focus highlighting, and return format. It does not mention error cases or constraints like SVG size limits, but the provided guidance is sufficient for correct invocation in most cases.

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%, and the input schema already documents each chart type's expected data structure in detail. The description adds interpretive value for chart selection and focus semantics, but most parameter meaning is already present in the schema, so the added semantic uplift is moderate.

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 'Create a presentation-ready data visualization from research findings,' which names a specific verb, resource, and context. It then enumerates all six chart types and states the output is a branded SVG, making the tool's function unmistakable and distinct from the non-visualization 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 clearly conveys when to use this tool: whenever a presentation-ready visual from research findings is needed, with a catalog of supported chart types matching different analytical needs. It does not explicitly state when not to use it or name alternative sibling tools, but the usage context is sufficiently 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 convey that the tool is readOnly, idempotent, and non-destructive, so extra credit is given for any increment beyond that. The description adds that the tool returns 'how to use them' along with the capabilities list, but it does not explain any behavior around the optional userId, response shape, or conditions under which the listing might be server-driven or personalized. It is not contradictory and does add some content scope, but it is a baseline behavioral disclosure.

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 and frontloads the core return value, then adds usage guidance. The list 'capabilities / features / offerings / products / services / tools' is somewhat redundant, but not wasteful enough to derail clarity. It 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?

For a simple, read-only, idempotent capability-list tool with one optional parameter and no output schema, the description is nearly complete. It lacks any mention of what userId does, which is a small but relevant gap since the parameter exists in the schema. Still, an agent has most of what it needs: purpose, return scope, and usage guidance.

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 only parameter is 'userId', described as an optional user identifier. The description mentions no parameter behavior, so it adds nothing beyond the schema. Since this meets the high-coverage baseline, 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 states a specific verb ('Returns') and resource ('Fodda's main capabilities / features / offerings / products / services / tools and how to use them'). It clearly conveys the purpose of the tool and is easily distinguished from sibling tools, none of which serve the same broad capability-discovery function.

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 second sentence gives explicit guidance: 'Call this for any question about what Fodda can do or what's available.' This defines clear usage context for an agent. However, it does not mention alternatives or when not to use this tool, so it falls short of the full 'when/when-not/alternatives' standard.

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

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

Annotations already cover the safety profile with readOnlyHint, idempotentHint, and destructiveHint hints. The description adds useful behavioral context by outlining the returned item fields and the deterministic lookup behavior. It doesn't discuss edge cases like missing nodes or empty results, but the described behavior is still substantially transparent.

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?

Four sentences, each with its own role: what for, what output looks like, when to use it, and how it differs from search. There is no superfluous wording and the most important 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?

Given that there is no output schema, the description explicitly describes the returned citation fields and attribution. Combined with the schema's complete parameter descriptions and the tool's annotation profile, the definition supplies all necessary information for the agent to decide when and how to 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?

Schema description coverage is 100%, so the baseline for this dimension is 3. The description's mention of 'direct lookup by trend ID' and 'after search_graph' adds no significant parameter-level detail beyond what the schema already says about graphId and for_node_id.

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

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

The description specifies a distinct verb and resource: getting the source articles, case studies, and statistics behind a specific trend, with a specific output shape including URLs and publisher attribution. It also distinguishes the tool from sibling tools by stating it is a direct lookup by trend ID, not a text search 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?

It gives explicit guidance on when to use the tool: 'Use after search_graph when you need the supporting proof behind a trend.' It provides an explicit exclusion: 'not a text search tool', which helps an agent route to the right tool among siblings such as search_graph.

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 annotations already declare readOnlyHint and idempotentHint, so no extra safety disclosure is needed. The description adds useful behavior: label="Trend" returns a deterministic and complete list, and search may return partial results, helping the agent anticipate output reliability. It does not contradict 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?

Three sentences, each earning its place: the first states the core action, the second gives practical examples, and the third reveals an important golden-path behavior. No filler, tautology, or redundant restatement of the name.

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 browsing tool with 100% schema coverage and no output schema, this description gives an agent everything needed: what the tool does, which inputs matter, and when its special deterministic behavior should be used. It is complete for selecting and invoking 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?

Schema coverage is 100% for graphId and label, so the schema already documents each parameter. The description adds semantic value by enumerating common labels and, importantly, by identifying the specific label='Trend' behavior that the schema alone would not express. It helps an agent choose the right value for the desired use case.

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 ('List all brands, locations, technologies, audiences, or trends') tied to a clear resource ('within a specific knowledge graph'). It directly supports the tool's listing purpose and distinguishes it from search-oriented tools by emphasizing complete, enumerable label values rather than fuzzy matches.

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

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

The description gives a clear use context ('Use to explore what a graph contains') and concrete example questions, such as 'what brands are in the retail graph?'. It also explains a specific beneficial scenario for label="Trend" (finding complete lists in industry-report graphs) and contrasts it with search tools' partial results, though it does not name the alternative sibling tool explicitly.

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. The description adds value by noting the tool returns 'live data — not cached from session start', which is useful behavioral context beyond what annotations provide. 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?

Two sentences: first states purpose and data returned, second provides usage examples and a behavioral note. Every sentence is informative and earns its place. Highly efficient and 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?

Given the tool's simplicity (no parameters, no output schema), the description covers all essential aspects: what the tool does, what data it returns, when to use it, and a key behavioral trait (live data). No 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?

There are zero parameters, and schema coverage is trivially 100%. The description correctly omits any parameter details. Baseline for 0 parameters is 4, and no additional information is needed.

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 ('Check') and resource ('current user's account status'), listing concrete data points (API call balance, plan, graphs, profile). It clearly distinguishes from sibling tools like get_capabilities or list_graphs by focusing on account-specific metrics.

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 the tool by giving example user queries ('how many API calls do I have?', 'what plan am I on?'). While it doesn't provide explicit when-not-to-use or alternative tool mentions, the context is sufficiently clear for an AI agent to select correctly.

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 annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds useful behavioral context by calling the output 'curated editorial connections' that web search cannot provide, giving the agent a realistic expectation about result semantics beyond a raw graph query 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?

The description is compact and front-loaded: it shares what the tool does, why it is different from search, when to use it, and the required precondition. Every sentence earns its place and no information is repeated from the annotations or schema.

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, combined with a fully detailed 7-parameter schema and the annotation set, is sufficient for the agent to know when and how to call the tool. There is no output schema, so a little more detail about the exact shape of the returned connections would make this a 5, but the current definition is not misleading or incomplete in a risky way.

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 the baseline is 3. The description's only parameter-specific instruction, 'Requires node_id from a prior search_graph result', is already stated in the seed_node_ids schema description, so the description adds little extra parameter-level knowledge beyond 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 clearly states the verb and resource: discover what is connected to a specific trend/node, including related brands, technologies, locations, and cross-domain links. It also explicitly contrasts this with plain search, making the tool's purpose distinct from search_graph and 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?

'Use after search_graph' gives a clear prerequisite and workflow position, and the description lists concrete use cases such as mapping the territory around a trend and finding connected brands. It does not explicitly state when not to use the tool or present alternatives like get_node or get_evidence, 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.

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

Annotations already disclose the read-only, idempotent, non-destructive nature of the tool. The description adds one behavioral constraint — node_id must originate from a prior search_graph result — but it does not describe return format, error conditions, or edge cases. This is reasonable credit beyond annotations but not rich.

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 carrying its weight: what the tool returns, when to use it, and what it requires. The purpose is front-loaded and there is no redundant or filler 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 read-only single-resource tool with two required parameters and a fully described schema, the description covers what, when, and the precondition. There is no output schema, but the description explicitly lists the attributes returned, so nothing critical for describing the tool is missing.

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

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

Schema description coverage is 100%, and the schema already explains the nodeId provenance caveat, graphId examples, and optional userId tracking. The tool description adds no parameter-level detail on top of the schema, so the baseline score 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?

States a specific verb and resource — 'Get the full profile of a specific trend' — and enumerates what the profile includes (detailed description, lifecycle stage, signal strength, geographic scope, and all properties). It also contrasts itself with search_graph by saying it provides deeper detail after a summary, so it is distinguishable 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?

Explicitly says when to use it ('when you need deeper detail on a single trend after search_graph returned a summary') and states the hard prerequisite that node_id must come from a prior search_graph result. It doesn't name alternatives such as get_neighbors or get_evidence or give exclusion conditions, so it stops 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.

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

Annotations already signal read-only and non-destructive behavior. The description adds value by disclosing parallel fan-out across 80+ authoritative sources, categorized return blocks, and source attribution metadata. It does not mention latency, rate limits, or errors, but the most important behavior is covered.

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 wastes little: it states what data is returned, when to call, what triggers the call, and which sources are used—all in a few sentences. It front-loads the core purpose and places the integration note at the end 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?

For a 6-parameter tool with no output schema, the description is solid: it covers the operative trigger, source scope, output type, and relevant examples. It could be stronger about expected result usage or edge cases like broad domains, but it is not incomplete enough to cause confusion.

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 the param descriptions already explain query, geo, brands, domain, graph_ids, and userId. The tool description adds context about the kinds of queries that benefit from supplemental data but does not materially deepen the meaning of individual parameters. 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 clearly identifies the tool as retrieving supplemental market data from a set of external sources and explicitly ties it to search_graph coverage gaps. It names a concrete resource type (macro, institutional, real-time market data) and distinct behavior (parallel retrieval from 80+ sources), helping an agent distinguish this from graph or research 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 gives explicit trigger conditions: use it when curated coverage is thin/empty, or when the query is demand/attention-shaped, and after search_graph indicates thin coverage. It does not enumerate when-not-to-use scenarios or alternative sibling tools beyond search_graph, but the conditions are specific enough to guide 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, idempotentHint, and destructiveHint false, covering safety. The description adds context that results are scoped to 'the user can access' (permission-filtered) and that it returns graph metadata needed for graphId parameters in other tools, which is useful behavioral information 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 two sentences and front-loaded with the core purpose, followed by usage guidance and downstream value. No unnecessary words or restatements, 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 listing tool with one optional parameter, rich annotations, and no output schema, the description covers purpose, content scope, and usage timing. It is complete for an AI agent 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 covers the single optional userId parameter with 100% description coverage, explaining automatic authentication for non-trial users. The tool description adds no additional parameter semantics, 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 states a specific verb and resource: 'List all expert knowledge graphs the user can access', and details the returned fields (IDs, descriptions, authors, sectors, signal counts, topic coverage). It distinguishes from siblings by framing itself as the session-first discovery tool before searching, which separates it from search_graph and deep_research_topic.

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 'Use FIRST in any session to discover available sources before searching', offering clear when-to-use guidance. It does not name alternative tools directly, but the 'before searching' cue implies its role relative to search-related siblings. No when-not-to-use exclusions are provided, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description explains the behavioral output: it cleans text and returns structured text ready for analysis. It hints at network fetch behavior and output format, though it does not mention failure modes like unreachable or auth-protected pages.

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, purposeful sentences: first states the core action, second gives the when-to-use context with concrete examples, third states the return value. No filler or repetition; essential 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 simple read-only URL extraction tool with a single required parameter, the description adequately covers selection, invocation timing, and return behavior. Even without an output schema, it clearly says the result is structured text ready for analysis, which is enough 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 coverage is 100%, so both parameters already have descriptions. The description's 'any URL' adds a minor scope note, but it does not provide any additional semantic value beyond what the input schema already offers, so baseline 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?

States a specific verb and resource: 'Extract clean text content from any URL.' The phrase about cross-referencing against knowledge graphs clarifies the exact use case, and the resource (URL) is distinct from sibling tools that query graphs like get_node or search_graph.

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 guidance: use when a user shares a link (competitor site, news article, client brief, trend report) and wants cross-referencing. It does not explicitly name alternatives or exclusions, but none of the sibling tools directly perform URL extraction.

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

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

Beyond the readOnlyHint annotation, the description reveals an important behavior: omitting graphId searches all accessible graphs in parallel. It also sets expectations on the result content (cited evidence, source attribution, lifecycle stage) and explicitly distinguishes it from generic web summaries. This is meaningful, non-obvious behavioral detail.

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 core purpose and return value, then adds the key behavior guidance, then the use-case list. Every sentence adds meaningful information and there is no filler or repeated schema content.

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 with 9 parameters and no output schema, the description covers the output shape, the main behavioral default, the use boundaries (national/global vs sub-national), and when to delegate to a sibling. Combined with the comprehensive schema, it is complete enough 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?

The input schema has 100% description coverage across all 9 parameters, so the baseline is 3. The description adds a little extra by recommending the default graphId behavior, but most parameter meaning is already carried by the schema, so the description doesn't need to compensate.

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

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

The description states a specific verb and resource — 'Find trends, signals, and expert insights across 100+ curated knowledge graphs' — and clearly differentiates this tool from generic web search by mentioning cited evidence, source attribution, and lifecycle stage. It is immediately clear what type of task this 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?

It explicitly says to use this tool for 'market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts' and gives the default recommendation to omit graphId to search all accessible graphs. It also points to get_supplemental_context when sub-national or city-level data is needed, which is strong when-vs-alternative guidance.

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