Bluebird Technologies

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the return format (Markdown), which is genuinely useful, but says nothing about what happens with long pages, whether content is truncated, or authentication requirements.

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

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

Two short sentences, front-loaded with the action and return format, then the input guidance. Nothing is wasted.

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 read tool with rich annotations, this covers what the agent needs: what it returns, how to build the input, and why the sibling tools matter. The only gap is the ambiguity of 'one page' (pagination vs. truncation), which could affect how agents chunk large 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?

Schema coverage is 0%, so the description must carry parameter meaning — and it does: 'id' can be a path-style id from search/list_pages or a full page URL, with a concrete example of the format. It doesn't mention the 500-character limit or error behavior for invalid ids, but the dual input modes are clearly explained.

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 ('Return one page of the website as Markdown'), and names the sibling tools that produce valid input (search, list_pages). It stops short of explicitly contrasting this with those siblings, but the output-format detail makes the tool's job distinct.

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 signals the prerequisite workflow: get an id from search or list_pages, then pass it here, with a concrete example ('/work/raubex'). No explicit when-not or exclusion cases are given, but the context for use is unambiguous.

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 description's key added value is confirming that no message is transmitted and that the user completes the form manually — exactly the side-effect question an agent would have. It also discloses the return shape (email address plus form link). It adds no rate-limit or fallback context, so it falls short of exhaustive.

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?

A single front-loaded sentence leads with the purpose and ends with the critical no-send caveat, which is good ordering. The parenthetical enumeration of all eight topic values duplicates the schema and adds bulk without adding meaning.

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-required-parameter lookup with no output schema and full annotation coverage, the description supplies what an agent needs: what comes back, that nothing is sent, and why the topic exists. The only meaningful gap is the unexplained enum value 'za'.

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 0% schema description coverage, the description does add the one genuinely missing piece: the topic is chosen for the enquiry form, which explains what the parameter is for. However, it merely re-lists the enum values already in the schema and leaves opaque values like 'za' unexplained, so an agent cannot confidently pick a topic.

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 concretely what the tool yields: an email address and a link to the enquiry form with a chosen topic. That is specific enough for an agent to know it is a static contact-info lookup rather than a messaging tool. It does not differentiate itself from the generic siblings (fetch, search, list_pages), but its purpose is unambiguous on its own.

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

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

The opening phrase 'How to start a conversation with Bluebird Technologies' sets the situation in which to call it, and 'It sends nothing; the user submits the form themselves' tells the agent what to do afterwards rather than attempting delivery. There is no explicit exclusion or reference to an alternative tool, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is fully covered by structured metadata. The description adds the useful scope detail that only 'public' pages are returned and that each carries a summary, but says nothing about ordering, pagination, or exclusion of drafts/private 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?

The first clause is tight and front-loaded, but the middle of the description is a flat enumeration of all twelve enum values that merely duplicates the schema's enum list. The two disambiguation sentences at the end earn their place; the raw enumeration does not.

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 optional-parameter read tool with no output schema, the description covers scope and filter semantics adequately. It stops short of describing what 'summary' contains or whether results are ordered/paginated, which an agent planning a listing call would want.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it names the parameter's domain and clarifies two ambiguous enum members ('case studies are kind case-study; engagement types are kind service'). The only shortfall is that it largely restates the enum values already present in the schema rather than explaining filtering behavior.

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 statement of scope: every public page with its summary, optionally narrowed to one kind. The enumerated kind list makes clear what resource is returned and distinguishes it from the fetch/get_contact/search siblings, though those alternatives are never named.

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 word 'optionally' signals that the kind filter is not required and that omitting it returns all pages, which is implied usage guidance. However, there is no explicit statement of when to use this tool instead of fetch or search, so the agent must infer the routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: it defines the indexed corpus as public pages only and discloses the return shape (page ids), which annotations cannot express. No result-count or ranking behavior is mentioned, keeping it just under a 5.

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

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

Two short sentences, zero filler, with the corpus scope and the return contract both front-loaded. Every clause earns its place.

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

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

For a one-parameter, read-only tool with full schema coverage and annotations covering the safety profile, this is sufficient: the agent knows the corpus, the input, and that output is page ids to hand to fetch. No output schema exists, so nothing further is strictly required.

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 is a single parameter with 100% schema description coverage ('What to look for, in plain language'), so the schema already carries the meaning. The description adds no extra guidance on query phrasing, length limits, or matching behavior, 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?

States a specific verb (search) plus the exact resource scope (every public page of the Bluebird Technologies site) and enumerates the sections covered. The closing clause 'Returns page ids for fetch' cleanly separates it from the fetch sibling, which consumes those ids.

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 'returns page ids for fetch' clause clearly implies the intended search-then-fetch workflow, giving an agent concrete usage context. It stops short of naming alternatives such as list_pages for enumerating everything or get_contact for contact details, so the when-not-to-use side is left to inference.

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