Vectree

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

No annotations are provided, so the description carries full behavioral burden. It discloses that only published collections are returned, that unknown slugs yield no collection, and that entries can be in a 'still generating' state. It does not explicitly state that this is a read-only fetch, but the verb 'Fetch' strongly implies it, and the described behavior is otherwise thorough.

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

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

The description is a few sentences but every sentence earns its place: the first sentence states the core function, the second explains what a collection is, and the subsequent sentences give actionable context about usage and edge cases. It is organized into clear paragraphs and is not padded.

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?

There is no output schema, but the description explains exactly what is returned (description, diagrams in curated order) and how to proceed with each entry via `get_diagram`. It also covers edge cases like 'still generating' and unknown slugs. An agent has everything needed to call this tool correctly and interpret the result.

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 schema already fully documents the `slug` parameter. The description adds usage context (e.g., where to get the slug) but essentially repeats the schema's guidance about list_collections results and URL segments. It does not introduce meaning beyond the schema, so the 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 ('Fetch') and a precise resource ('one Vectree collection'), then spells out what it returns: description and diagrams in curated order. It also distinguishes itself from siblings like `get_diagram` and `list_collections`, so an agent can select it correctly without opening schemas.

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

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

Explicitly says 'Use it after list_collections, or whenever you already know a collection slug', and gives a clear exclusion: skip entries marked 'still generating'. It also notes that only published collections can be fetched and that nothing is generated on demand, which shapes call expectations.

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?

With no annotations, the description carries the full burden and handles it well: it states that nothing is generated on demand and an unknown slug simply has no diagram, clarifying the failure mode. It also discloses the read-only nature of the fetch and gives the practical consequence (no need to fetch the page). A minor omission is the lack of an exact error/return convention for non-existent diagrams, though 'simply has no diagram' covers the core 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?

The description is compact and starts with the main action, followed by context, usage, and constraints. Every sentence contributes meaning, though 'returns the complete text of one of them' slightly restates the opening 'full content' phrase. This is a minor redundancy in an otherwise efficient description.

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?

There is no output schema, so the description must stand in for return-value documentation—it does, listing labelled nodes, explanations, image URLs, and outgoing links. It also covers chaining, public-only access, and the unknown-slug case, making it complete for an agent deciding whether and how to call the tool. Nothing critical is missing.

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

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

The input schema already documents the single `slug` parameter with concrete examples (search_diagrams result or URL path segment), so the baseline is 3. The description adds one useful detail—that `Linked diagrams` and `Related diagrams` produce slugs that can be passed straight back—but otherwise does not need to add more because the schema is comprehensive. Score is at baseline.

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 ('Fetch') and resource ('full content of one Vectree diagram'), then enumerates exactly what is returned (labelled nodes, explanations, image URLs, links). This clearly differentiates it from the collection/learning-path siblings by focusing on diagram content, even without naming them explicitly.

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 when-to-use instructions: 'Use it after search_diagrams to read a result in depth, or whenever you already know a Vectree slug.' It also explains a follow-up pattern (passing linked/related slugs) and warns that only public, already-generated diagrams can be fetched. It does not explicitly mention the sibling collection/learning-path tools as alternatives, which is the only gap.

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?

With no annotations provided, the description carries the full behavioral burden and discloses several non-obvious traits: only published paths are fetchable, nothing is generated on demand, an unknown slug 'simply has no path,' and the whole ordered sequence is returned at once. It stops short of specifying the exact not-found representation (empty list vs. error), which keeps it from a 5.

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

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

The core purpose is front-loaded in the first sentence, and each paragraph earns its place: definition/scope, usage flow, and behavioral constraints. The second paragraph defining a learning path is helpful for sibling discrimination but slightly verbose for a one-parameter read 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?

For a single-parameter tool with no output schema, the description covers return semantics (ordered steps, each with a diagram slug), the sibling workflow (search → fetch path → get_diagram), and edge cases (still generating, unpublished, unknown slug). It could be more explicit about the top-level return structure, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100% and the slug parameter is already well documented with examples of how to source it (query result or URL segment). The description reinforces this by pointing to search_learning_paths results and known slugs, but it adds no genuinely new information beyond the schema, so the 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?

The first sentence states a specific verb and resource: 'Fetch one Vectree learning path: its ordered steps, each naming the diagram that step teaches.' It clearly distinguishes this fetch-one-path tool from siblings like search_learning_paths, get_diagram, and get_collection, and the term 'one' is reinforced by 'Only published paths can be fetched.'

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 when-to-use context: 'Use it after search_learning_paths, or whenever you already know a path slug.' It also explains how the output feeds the next step via get_diagram and warns to skip steps marked 'still generating.' It does not explicitly state when not to use it versus get_collection or list_collections, so exclusions are missing.

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 are absent, so the description carries the full burden of behavioral disclosure. It does add useful behavior: 'Only published collections are listed' and 'nothing is generated on demand', which clarifies the read-only, non-dynamic nature. However, it omits details like pagination, ordering, or return format, which would be needed for a fully transparent list operation. The extra behavioral notes justify a solid 3 but not a 4.

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 written: a front-loaded definition, a brief context sentence, a clear usage sentence with alternatives, and a practical note about slugs. Every sentence earns its place without fluff or repetition, making it easy to scan.

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 there is no output schema, the description compensates by explaining the collection concept, mentioning the slug for get_collection, and clarifying published-only behavior. It lacks explicit return-field details or pagination, but for a browse tool the core information is present. A small gap keeps it from a 5.

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 schema fully documents the optional 'type' filter with its enum and meaning. The description adds no extra parameter semantics beyond that, which fits the baseline 3 for high coverage. It does hint at themed sets but does not map directly to the enum values.

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 statement: 'List Vectree's curated collections' and specifies the content type (hand-assembled groups of diagrams). It differentiates from siblings by naming alternatives like search_diagrams and search_learning_paths, so an agent can confidently choose this tool for browsing.

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 ('to browse', 'to answer what is on Vectree?', 'to find a themed set of diagrams') and when not to use it ('When the user already has a topic in mind, use search_diagrams; when they want an ordered syllabus, use search_learning_paths'). It also tells the agent to pass the slug to get_collection for interior diagrams, covering downstream 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?

With no annotations, description carries full burden and excels. It discloses that search is semantic, results are ranked by match and quality, each result includes a slug, and only public pre-generated diagrams are searched. It also explicitly states that no on-demand generation occurs—valuable behavioral context not inferable from 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 well-structured with a clear intro, usage guidance, ranking explanation, and limitations. Every sentence adds value; no fluff. Front-loaded with core purpose, then usage, then behavior, then caveat.

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 only 2 parameters with full schema coverage and no output schema, the description covers all essential context: what tool does, when to use, how queries work, what results contain, and limitations. The link to get_diagram provides necessary next-step guidance. Nothing relevant 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 coverage is 100%, providing full descriptions for both parameters. The description adds extra meaning by explaining that the query should be natural language and that a full question works better, which goes beyond schema's generic example. It also clarifies limit's default behavior implicitly through schema, but description adds semantic search context.

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

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

The description provides a specific verb phrase ('Search Vectree's library of ~95,000 interactive concept diagrams by meaning, not keywords') that clearly distinguishes this tool from keyword searches and names the resource. It also differentiates from siblings by explaining the semantic nature and mentioning the relationship to get_diagram.

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: 'when the user wants a diagram, a visual explanation, a systems overview, or a map of how the parts of something fit together.' It also gives guidance on query formulation (full question works better than a bare keyword) and notes that nothing is generated on demand, implying no fallback. This provides clear context for selection over alternatives.

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?

With no annotations, the description carries full weight. It discloses that search is semantic, that only published paths are searched, that nothing is generated on demand, and that unmatched subjects have no path. This gives an accurate model of what the tool does and does not do.

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 average but every paragraph contributes: what learning paths are, when to use this tool vs. alternatives, querying guidance, and behavioral caveats. The structure is logical with a clear opening statement, though the intermediate explanatory paragraph about Vectree could be trimmed without losing essential guidance.

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 two-parameter search tool with no output schema and no annotations, the description fully covers purpose, usage, parameter semantics, and edge cases. An agent has everything needed to call it correctly and interpret the result caveats.

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 both parameters. The description adds meaningful context beyond the schema by explaining that query should be natural language and that full sentences work better than keywords, which helps the agent construct a better query.

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 precise verb and resource: 'Search Vectree's curated learning paths' and distinguishes them from individual diagrams. It explicitly names the sibling 'search_diagrams' as the alternative for single topics, so an agent can tell exactly which tool to pick.

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 an explicit when-to-use rule ('learn, study or get started with a whole subject') and names the alternative with the condition that selects it ('specific topic explained... use search_diagrams'). Also advises on query phrasing, which is directly actionable.

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