Codemate website

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

Annotations only declare readOnlyHint=true, so the description must carry the rest, and it does: it discloses that only Codemate-verified facts are returned and that absence of a field means the fact is unpublished, so the agent must not infer. That is genuine behavioral guidance beyond the safety hint, though it says nothing about freshness, response shape, or caching.

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: purpose, routing rule, and the no-inference guarantee. The purpose is front-loaded and there is no filler.

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

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

With no output schema, the description does the work of saying what comes back (company facts) and guaranteeing completeness. It leaves only one minor gap for a one-parameter read tool: it never mentions that results are drawn from a language-specific edition.

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 single lang parameter already documents the en/fi enum and the English default. The description adds nothing about language editions, 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 ('Get authoritative facts about Codemate as a company') plus the scope of that data (what it does, legal entities, other published material). An agent can distinguish this from get_contact_info or get_page_data without inspecting any schema.

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?

Gives an explicit trigger ('when asked to describe or introduce Codemate') and an explicit exclusion with named alternatives ('rather than assembling an answer from service pages and articles'). This is a clear when-to-use and when-not-to-use statement.

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 readOnlyHint=true already covering the safety profile, the description adds real value by disclosing the exact shape of the returned content (addresses with map links, people with role/email/phone/LinkedIn/photo, general sales contacts), which compensates for the absence of an output schema. It does not mention auth, rate limits, or result size, keeping it short of 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 sentences, front-loaded with the resource and payload, then the usage trigger. The field enumeration is dense but each item is informative rather than filler; no wasted preamble.

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 lookup with no output schema, the description supplies the returned field inventory and the filtering options, and the schema covers lang editions. An agent has everything needed to decide to call it and how.

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 documents lang, role, and office with examples. The description only restates the filtering concept ('Filter by role or office') without adding syntax or matching semantics 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?

Names a specific verb (get) and resource (contact info) and then enumerates the concrete payload: office addresses with map links, named people with role/email/phone/LinkedIn/photo, and general sales contacts. This is clearly distinguishable from siblings like get_company_info or list_open_positions.

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 it: 'when asked how to contact Codemate, who to speak to about something, or where its offices are,' and notes the role/office filtering affordance. It does not name a sibling as the alternative or state when-not to use it, 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the return shape (title, date, metadata, the page's prose) and the key behavioral distinction that search results are summaries only. It stops short of stating pagination or size limits for long articles, which is the one remaining gap.

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, zero filler, with the core action and its input source front-loaded and the sibling disambiguation last. Every sentence carries distinct 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?

There is no output schema, so the description must and does summarize the return (title, date, metadata, prose). With one 100%-documented parameter and readOnlyHint covered, an agent has everything needed to call this 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%, so the baseline is 3. The description adds provenance value by naming the three sibling tools (search_site, list_articles, list_references) whose output feeds this parameter, telling the agent where a valid URL comes from rather than just what type it is.

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 ('read the full text') and resource ('a codemate.com article or client case study'), and scopes it to the URL-shaped input. It explicitly contrasts itself with get_topic for service/product pages, so the agent can separate it from siblings without opening a schema.

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?

Gives explicit when-to-use ('Use this after a search to actually read a result'), why ('search only returns a summary'), and names the sibling to use instead for other page types (get_topic). Nothing about selection 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.

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

The readOnlyHint annotation already covers the safety profile, and the description adds valuable return-shape information: page summary, sections, and FAQ. It also implies language-specific editions. It does not mention whether content is cached, paginated, or truncated, so it is not fully transparent, but it clearly exceeds what the annotation supplies.

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 tight sentences, front-loaded with the core action, then scope, then return contents, then usage. Every sentence carries information and nothing is 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, so the description correctly compensates by naming what is returned (summary, sections, FAQ). Combined with the enumerated ids and usage contexts, an agent has enough to invoke it correctly; only edge details like language fallback behavior are left implicit.

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 both parameters have enums documented, so the schema does the heavy lifting; the description restating the valid id list is largely redundant. The lang parameter and its 'fi' option are not addressed in the description at all, so no meaning is added 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?

Specific verb ('Read the full text') plus a clearly scoped resource ('one of Codemate's main pages'), with the full set of valid ids enumerated so the agent knows the exact universe of pages. This is far more precise than the generic siblings (get_page_data, search_site) and lets an agent select it without opening the schema.

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 the answering contexts: Codemate's services, delivery model, AI transformation offering, and the Paimen platform. That is clear when-to-use guidance. It stops short of naming when NOT to use it versus siblings like search_site or get_page_data, so no exclusion guidance is provided.

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 only declare readOnlyHint=true, so the description usefully adds behavioral context the annotation lacks: results are ordered newest first and include date, category, summary and URL. It does not mention pagination behavior or that lang selects the underlying site edition beyond what the schema says, but the added context is substantive.

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, zero waste. What the tool returns and how it is ordered comes first, and the routing hint to search_site is placed last as a contrast.

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

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

With no output schema, the description compensates by naming the returned fields and ordering, and it covers filtering and the sibling alternative. Only minor gaps remain (no pagination or rate-limit note), so it is complete enough to call 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 all four parameters (lang, limit, since, category) are already documented in the schema, including enums and defaults. The description restates filtering by category/date without adding syntax or format detail beyond the schema; 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 ('List Codemate's published articles') plus ordering ('newest first') and the fields returned (date, category, summary, URL). An agent can distinguish this from the sibling list_* tools and search_site without opening the schema.

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?

Gives an explicit use case ('what Codemate has written or published about something, or for recent news') and names the competing alternative with the discriminating condition: search_site only returns the closest few matches. That is a clear when-to-use plus when-to-prefer-another.

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 only declare readOnlyHint=true; the description adds that the result carries location, job page URL, and application link, which matters since there is no output schema. It omits pagination or rate-limit behavior, but for a small read-only listing that gap is minor.

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 tight sentences: the first states what is returned, the second states when to call it. Nothing redundant, and the payload description 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 read-only, zero-required-param listing tool with no output schema, the description covers both purpose, return contents, and invocation triggers. An agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100%, so both 'lang' (with enum and default) and 'location' are already documented in the schema. The description's mention of location adds no syntax or format detail beyond what the schema provides, 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?

Specific verb ('List') plus a precise resource ('jobs Codemate is currently hiring for') and even the return fields (location, job page URL, application link). It is clearly separable from siblings like list_articles or get_company_info without opening either schema.

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?

Explicit trigger conditions are given: 'when asked whether Codemate is hiring, or about careers and open roles.' It doesn't name an alternative or state when not to use it, but the usage context is unambiguous for a single-purpose listing tool.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile, so the bar is lowered. The description adds useful return-shape context (which fields come back) and the filtering/scope behavior, but says nothing about pagination, result caps, or how the lang edition affects filtering. Adequate 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?

Two sentences, front-loaded with the tool's purpose and pay-off fields, then the routing rule against search_site. Every clause earns its place with no filler.

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 exists, but the description compensates by enumerating the returned fields, and the param set is fully covered by the schema. For a 4-param, zero-required read-only listing tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters (lang, client, service, industry) are already documented with examples in the schema. The description restates the filter axes ('filter by industry, service or client') without adding syntax, matching rules, or combination semantics beyond what the schema provides. 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+resource (list Codemate's client case studies) and enumerates the returned fields (client name, industries, services, summary, URL), making the tool's output immediately legible. It further distinguishes itself from the sibling search_site by noting that search_site only returns the closest few matches and mixes in articles.

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 names the triggering intent — 'when asked what Codemate has delivered, for whom, or for proof of experience in a sector' — and contrasts it with the alternative search_site and that sibling's limitation. Nothing about tool selection 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.

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

With readOnlyHint=true already declaring the safe-read profile, the description adds the return contract: best-matching titles with URLs and a one-line summary. That is genuinely useful context given there is no output schema. It stops short of any detail on result ranking, pagination, or empty-result 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 tight sentences: purpose first, then the return shape, then usage contexts. No filler, and the most important scoping 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 read-only search tool with a fully documented schema and no output schema, the description covers purpose, coverage, and return shape adequately. Minor gaps remain around result ordering and what happens when nothing matches.

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 documents kind, lang, limit and query with enums and defaults. The description adds no parameter-level semantics beyond that, 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 description opens with a specific verb+resource ("Search Codemate's website") and enumerates the three content types it covers (service pages, client case studies, articles). It does not name or contrast against the enumeration siblings (list_articles, list_references, get_page_data), so the agent must infer the search-vs-list distinction.

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 concrete when-to-use conditions: finding what Codemate does, which industries/technologies it has delivered in, or whether it has written about a topic. There is no explicit when-not guidance or named alternative (e.g., use list_articles to enumerate instead of search), so routing between siblings 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.