Shlok Bam's portfolio

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: the granular fields returned per section, the fact that results can be scoped by kind, and that a portfolio page link accompanies the data.

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?

Front-loaded with the resource and its contents, then the return behavior, then the sibling hand-off — a sensible order. The parenthetical field lists make the first sentence dense, but every element aids selection and none is 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 still explains both the scoping behavior and the shape of the response, including the supplementary portfolio link. For a single-optional-enum read tool, nothing an agent needs to call it correctly 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% and the enum's own description already spells out all five values, so the schema carries the semantics. The description adds modest gloss on what the sections contain (community = mentoring, volunteering, event anchoring) but no new rules on how 'kind' interacts with defaults or invalid values, so it stays at the 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?

Specific verb and resource, plus an enumeration of exactly what is covered: patents (with title, status, office, reference number, summary, document link), awards/hackathons, certifications, and community work. It also names the sibling it is not (get_experience), so an agent can route 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?

States the selection rule explicitly: return everything or just the part named in 'kind', and hand off jobs/club roles to get_experience. That is a concrete when-to-use and when-not-to-use pair with the alternative named.

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?

Goes well past the annotations: public-repositories-only scope, exclusion of scheduled and automated commits, a 30-minute cache, and a documented failure return of {"error", "github"}. The readOnly/idempotent/openWorld hints already cover safety, and the description adds the operational facts an agent actually needs to interpret stale or missing data.

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?

Front-loaded with what is returned, then scope limits, caching, and error behavior, then the sibling pointer — a sensible order with little waste. 'Takes no input' mildly restates the empty schema, and the error-shape notation is slightly malformed, but neither costs much.

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 carries the full burden of describing returns and does so field-by-field (repository, message, date, link) plus counts. Caching, error behavior, and exclusions round out everything an agent needs to call and interpret 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?

There are zero parameters and the description states 'Takes no input', which matches the empty schema. Nothing more is required, though it adds no meaning beyond confirming the schema's emptiness.

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 combination with concrete scope: commit counts for 7 and 30 days, repositories touched this week, and the 12 most recent commits with named fields. It also carves out what is excluded (automated/DailyDiff commits, non-public repos), so an agent can distinguish it from portfolio siblings like get_profile 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?

Explicitly routes the agent to get_profile (rightNow) for monthly focus, which is real alternatives guidance, and states 'Takes no input' so invocation is unambiguous. It stops short of a full when-not-to-use statement (e.g., that this is not a search or historical archive tool), so it is strong rather than exhaustive.

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 annotations, the description discloses ordering (newest first), the fields present on every entry, the absence of input, and important exclusions such as pay and confidential client details. Since there is no output schema, these details are especially valuable and give the agent a clear picture of what a successful call will contain.

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 resource scope and ordering, then adds return fields, input behavior, exclusions, and sibling routing. Every sentence contributes useful information, and there is no unnecessary 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?

For a zero-parameter read-only retrieval tool with no output schema, the description is complete enough to call correctly. It explains the content, the shape of returned entries, the ordering, exclusions, and where to go for related data that is not returned here.

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 tool has zero parameters, so the schema is inherently empty and the baseline is 4. The description reinforces this with “Takes no input,” which is useful confirmation but does not add parameter-level semantics beyond the absence of arguments.

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 names the exact resource: work experience, leadership roles, and education, with specific parenthetical scopes like internships and student clubs. It also explicitly distinguishes this tool from get_achievements and list_projects, so an agent can immediately tell what this tool returns and what it does not.

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 states the intended content directly and gives explicit routing for adjacent needs: patents, awards, and certifications go to get_achievements, while projects go to list_projects. The exclusions and alternatives make selection between these common portfolio sections 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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile needs no restating here. The description still adds genuine context beyond them: data is pulled from the live site and refreshed roughly every 10 minutes, the tool takes no input, and 'Pay is not included' sets a negative scope boundary. It stops short of stating pagination or response size, but for a zero-parameter read tool that 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?

Front-loads the scope (what the profile covers), then routing, then behavioral notes in a logical order. The long enumeration of contents is dense but each item aids routing decisions; a couple of the link names (LeetCode, journal) could be trimmed without loss.

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 and no parameters, the description carries the burden of telling the agent what comes back, and it does so exhaustively, including the freshness of the data and an explicit exclusion (pay). Nothing an agent needs in order to call it correctly or interpret the result 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?

Zero parameters, so the baseline is 4. The description correctly reinforces this with 'Takes no input', leaving no ambiguity about whether filters or arguments are accepted.

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 concrete resource (the personal profile of Shlok Bam) and enumerates exactly what it contains: summary, role, education, location/time zone, openness, story, headline numbers, current focus, contact details and links. An agent can distinguish it immediately from get_resume, get_skills or get_experience without opening 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 default ('Call it first for any general question, or for contact details') plus a per-sibling routing table: list_projects/get_project for work, get_experience for jobs and clubs, search_portfolio for anything specific. Both when-to-use and when-to-use-something-else are stated.

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 the description adds real behavioral context beyond them: case-insensitive punctuation-ignoring matching, exact-then-substring precedence, the GitHub fallback with an explanatory note, and the exact error payload shape.

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?

Front-loaded with the payload description, then matching rules, then fallbacks, then the routing hint. Dense but every clause carries information; the parenthetical link list and example are slightly verbose but not wasteful.

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 carries the return-value burden and does so thoroughly (fields returned, GitHub enrichment, error shape), and it covers the single parameter's matching behavior completely.

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, but the description adds genuine meaning: matching is case-insensitive, punctuation is ignored, and partial names work ('workforce' finds the Enterprise Workforce Training Platform), which the schema only hints at via examples.

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 ('Full details of one of Shlok's projects') and enumerates the returned content (results, metrics, tech stack, rank, GitHub details, links), which clearly separates it from list_projects and the other get_* 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 routes the agent: 'Use list_projects first when you don't know the name,' and describes the fallback chain (featured projects → public GitHub repos → error with all project names) so the agent knows what happens on a miss and how to retry.

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, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the payload (links to a PDF and a web copy) and warning that the substantive content lives inside those documents rather than in the response fields. No output schema exists, so this return-shape note is doing real work.

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 short sentences, front-loaded with what the tool returns, followed by the no-input note and the sibling routing. Nothing is padded; the only mildly redundant phrase ('Takes no input') is a cheap and useful confirmation against the empty 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?

For a trivial, zero-parameter, read-only tool with no output schema, the description covers everything an agent needs: what it returns, that it needs no arguments, and when a sibling is a better fit. 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?

There are zero parameters, which sets the baseline at 4. The description reinforces this with 'Takes no input', removing any doubt about whether filters or identifiers are expected.

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 ('Links to Shlok's résumé') and enumerates exactly what comes back: a PDF download, a web version, plus title, summary, current role and education. It also explicitly distinguishes itself from the structured-data siblings, so an agent can choose without opening 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 a clear routing rule: use get_experience, get_skills and list_projects when the same facts are wanted as structured data, implying this tool is for the document itself. It stops short of an explicit 'use this when the user wants the résumé file/download' statement, but the alternative and its condition are named.

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/closed-world, so the description focuses on what annotations cannot express: within-group ordering ('strongest first'), the four-level scale, and the six-project cap on usedIn with the caveat that matching is by name and is 'a pointer, not a complete list.' That caveat is genuinely useful for an agent reasoning about coverage. Minor gap: no note on output size or whether groups can be empty.

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?

Front-loaded with what the tool returns, then semantics of each field, then the alternative. The parenthetical enumeration of all eight group names is somewhat long but doubles as a preview of the return values. No filler sentences.

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 carries the burden of describing the response and does so thoroughly: grouping, ordering, level values, and the usedIn field with its cap and reliability caveat. Combined with the routing hint to get_project, an agent has everything needed to call and interpret this tool.

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?

Zero parameters, so the baseline is 4. The description still adds value by confirming 'Takes no input,' removing any doubt an agent might have about optional filtering arguments.

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 ('Shlok's skills') and immediately enumerates the eight groups and the ordering rule, so an agent knows exactly what comes back. It is clearly distinguishable from siblings like get_project, list_projects, or get_experience, which cover different portfolio facets.

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 'Takes no input' and routes the agent onward: 'For proof of a skill, open those projects with get_project.' That is a concrete alternative and follow-up path. It stops short of stating when NOT to use this tool (e.g. versus get_resume for a narrative summary), so it is not a full when/when-not treatment.

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 value beyond that by disclosing result ordering (newest first) and the empty-result contract (count 0 and an empty list), though it says nothing about result volume or pagination for large blogs.

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 short sentences, front-loaded with what the tool returns before the filter rules and the sibling pointer. Minor redundancy with the schema's own parameter text, but no filler or throat-clearing.

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 return fields, ordering, filter matching rules and the empty-result case. Nothing an agent needs in order to call it correctly 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 states that the topic filter is case-insensitive and matched as part of the topic tag, title or summary, with examples and an empty-for-all rule. The description restates essentially the same semantics (adding only the 'agent' → Agents illustration), so it adds little meaning beyond the structured field — 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?

States a specific resource (Shlok's technical blog posts / journal) and enumerates exactly what each item contains (title, date, topic tag, summary, link) plus ordering (newest first). It also explicitly distinguishes itself from get_project, which covers the projects the posts describe, so an agent can route correctly 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 says to leave the topic filter empty to retrieve every post, and names the alternative tool (get_project) for the adjacent need. The no-match condition is also spelled out, leaving little for the agent to infer about when and how to call it.

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 discloses that filters are conjunctive, that a zero-match filter yields count 0 rather than an error, and that GitHub details are cached up to 6 hours and absent for private repos or when GitHub is unreachable. Those failure modes and staleness bounds are exactly the context an agent cannot infer from 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?

Purpose and ordering come first, then the shape of each entry, then filter semantics, then caveats, then alternatives to sibling tools. Every sentence carries non-redundant information, including the entry-composition sentence, which compensates for the absent output 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?

With no output schema, the description takes on the burden of describing return fields (name, slug, field, summary, tech stack, links, GitHub stars/language/topics/last update) and does so. Combined with caching behavior and the empty-result contract, an agent has everything needed to call this and interpret the response.

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 tech, category, and the two booleans are already fully documented, and the description adds little per-parameter detail. The one addition is the cross-parameter rule that all filters must match, which the schema states only for flagship_only, so this sits at the high-coverage baseline with a small increment.

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?

Opens with a specific verb and resource ("List Shlok's projects") plus scope and ordering ("in order of importance (the first five are flagships)"). It also separates itself from get_project and search_portfolio by name, so an agent can route without opening 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?

The final sentence gives explicit alternatives and the condition that selects each: get_project for a single project's full write-up and metrics, search_portfolio for non-project topics like a skill or award. That is a genuine when-to-use/when-not-to-use split rather than an implied one.

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 safety needs no restating. The description goes beyond them by disclosing the result cap ('up to 8 matches'), ordering ('best first'), per-result fields (type, title, snippet, link), and the empty-result behavior — exactly the operational traits an agent needs to interpret output.

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 doing distinct work: capability, return contract, usage context, sibling routing. It is front-loaded with the capability and the trailing sibling list is compressed into parallel clauses rather than prose.

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 search tool with no output schema, the description supplies the return shape, ranking, result limit and empty-result case, plus routing to the other nine tools. Nothing material is missing for correct invocation or interpretation.

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% and the query parameter's own description already documents case handling, punctuation, prefix matching, title weighting, exact-phrase boosting and examples. The prose description adds no query semantics beyond that, so the baseline 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?

The description opens with a specific verb and resource ('Search everything in Shlok's portfolio') and enumerates the content types covered (projects, experience, leadership, education, patents, awards, certifications, community work, blog posts). It explicitly distinguishes itself from get_project, list_projects, get_experience and get_achievements, so an agent can route without opening 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?

It states the positive condition ('specific questions the other tools don't answer directly, such as where he used a technology or whether he has done something') and then names four concrete alternatives with the condition that selects each. Both when-to-use and when-to-use-something-else are covered.

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